Doxygenは、ナビゲートや探し物を容易にするために、様々な方法でソースコードをインデックス化します。しかし、キーワードで何かを検索したい場合もあります。
HTMLブラウザはデフォルトで複数ページにわたる検索機能を持っていないため、Doxygenまたは外部ツールがこの機能を容易にする必要があります。
Doxygenには、HTML出力に検索機能を追加する7つの異なる方法があり、それぞれに長所と短所があります。
最も簡単な検索の有効化方法は、組み込みのクライアントサイド検索エンジンを有効にすることです。このエンジンはJavaScriptとDHTMLのみを使用して実装されており、クライアントのブラウザ上で完全に動作します。そのため、動作させるための追加のツールは必要ありません。
これを有効にするには、設定ファイルでSEARCHENGINEをYES
に設定し、SERVER_BASED_SEARCHがNO
に設定されていることを確認してください。
この方法の追加の利点は、ライブ検索を提供することです。つまり、検索結果は入力中に提示され、適応されます。
この方法には欠点もあります。検索対象がシンボルのみに限定されます。フルテキスト検索機能は提供されず、非常に大規模なプロジェクトにはうまくスケールしません(検索が非常に遅くなるため)。さらに、検索はインデックス化された項目の先頭から行われるため、利用可能な項目がA_STRING
、AA_STRING
、STRING
であり、検索ボックスにA
と入力すると、A_STRING
とAA_STRING
が見つかりますが、例えばSTR
と入力すると、STRING
のみが見つかり、A_STRING
は見つかりません。
HTMLドキュメントをウェブサーバーに配置する予定で、そのウェブサーバーがPHPコードを処理する能力を持っている場合、Doxygenの組み込みサーバーサイド検索エンジンも使用できます。
これを有効にするには、設定ファイルでSEARCHENGINEとSERVER_BASED_SEARCHの両方をYES
に設定し、EXTERNAL_SEARCHをNO
に設定します。
クライアントサイド検索エンジンに対する利点は、フルテキスト検索を提供し、中規模プロジェクトにうまくスケールすることです。
欠点は、ローカル(つまり、"file://" URLを使用)では動作しないことと、ライブ検索機能を提供しないことです。
Doxygenのリリース1.8.3で、別のサーバーベースの検索オプションが追加されました。このオプションを使用すると、Doxygenは検索可能な生データを生成し、インデックス作成と検索は外部ツールに任せるため、独自のインデクサーと検索エンジンを選択して使用できます。Doxygenには、Xapianオープンソース検索エンジンライブラリに基づいた、例示的なインデクサー(doxyindexer)と検索エンジン(doxysearch.cgi)が同梱されており、使いやすくなっています。両方のバイナリはディストリビューションに含まれていますが、デフォルトではインストールされていません。必要に応じてbin
フォルダから例えば/usr/local/bin
や/var/www/cgi-bin
に手動でコピーできます。
この検索方法を有効にするには、SEARCHENGINE、SERVER_BASED_SEARCH、EXTERNAL_SEARCHをすべてYES
に設定します。
設定の詳細については、外部インデックスと検索を参照してください。
オプション2に対する利点は、この方法が(潜在的に)非常に大規模なプロジェクトにスケールすることです。複数のDoxygenプロジェクトと外部データを1つの検索インデックスに組み合わせることも可能です。検索エンジンとのやり取りの方法により、ローカルHTMLページから検索することができます。また、検索結果のランキングが向上し、コンテキスト情報(利用可能な場合)が表示されます。
欠点は、CGIバイナリを実行できるウェブサーバーと、Doxygen実行後の追加のインデックス作成ステップが必要なことです。
WindowsでDoxygenを実行している場合、Doxygenによって生成されたHTMLファイルからコンパイル済みHTML Helpファイル(.chm)を作成できます。これは、すべてのHTMLファイルを含む単一のファイルであり、検索インデックスも含まれています。この形式のビューアは多くのプラットフォームで利用可能であり、Windowsではネイティブにサポートされています。
これを有効にするには、設定ファイルでGENERATE_HTMLHELPをYES
に設定します。DoxygenにHTML Helpファイルをコンパイルさせるには、HHC_LOCATION設定オプションを使用してHTMLコンパイラ(hhc.exe)へのパスを指定し、CHM_FILEを使用して結果のCHMファイルの名前を指定する必要があります。
この方法の利点は、結果が配布しやすい単一のファイルであることです。また、フルテキスト検索も提供します。
欠点は、CHMファイルのコンパイルがWindowsでのみ動作し、MicrosoftのHTMLコンパイラが必要なことです。Microsoftによるサポートはあまり活発ではありません。ツールはほとんどの人にとって問題なく動作しますが、時には明らかな理由もなくクラッシュすることがあります(いかにも典型的です)。
macOS 10.5以降でDoxygenを実行している場合、Doxygenによって生成されたHTMLファイルから「doc set」を作成できます。doc setは、HTMLファイルとプリコンパイルされた検索インデックスを含む特別な構造を持つ単一のディレクトリで構成されています。doc setは、Xcode(Appleが提供する統合開発環境)に埋め込むことができます。
doc setの作成を有効にするには、設定ファイルでGENERATE_DOCSETをYES
に設定します。設定したい他のdoc set関連のオプションがいくつかあります。Doxygenが完了すると、HTML出力ディレクトリにMakefileが見つかります。このMakefileで "make install" を実行すると、doc setがコンパイルおよびインストールされます。詳細については、この記事を参照してください。
この方法の利点は、Xcode開発環境とうまく統合され、例えばエディタで識別子をクリックしてDoxygenドキュメントの対応するセクションにジャンプすることができます。
欠点は、macOS上のXcodeとの組み合わせでのみ動作することです。
Qtアプリケーションフレームワークを開発またはインストールする場合、Qt assistantというアプリケーションを入手できます。これは、Qt Compressed Helpファイル(.qch
)用のヘルプビューアです。
この機能を有効にするには、GENERATE_QHPをYES
に設定します。また、QHP_NAMESPACE、QHG_LOCATION、QHP_VIRTUAL_FOLDERなど、他のQtヘルプ関連のオプションも入力する必要があります。詳細については、この記事を参照してください。
機能面では、Qt compressed help機能はCHM出力と同等であり、QCHファイルのコンパイルがWindowsに限定されないという追加の利点があります。
欠点は、各ユーザーがQt 4.5(またはそれ以降)をセットアップするか、ドキュメントと一緒にQt help assistantを配布する必要があることですが、現時点では個別のパッケージとして入手できないため、複雑になっています。
Eclipseを使用している場合、Doxygenによって生成されたドキュメントをヘルププラグインとして埋め込むことができます。これは、ヘルプメニューの "ヘルプコンテンツ" から起動できるヘルプブラウザのトピックとして表示されます。Eclipseは、キーワードを最初に検索するときに、ドキュメントの検索インデックスを生成します。
ヘルププラグインを有効にするには、GENERATE_ECLIPSEHELPをYES
に設定し、ECLIPSE_DOC_IDを介してプロジェクトの一意の識別子を定義します。例:
GENERATE_ECLIPSEHELP = YES ECLIPSE_DOC_ID = com.yourcompany.yourproject
次に、eclipseのplugin
ディレクトリにcom.yourcompany.yourproject
ディレクトリ(ECLIPSE_DOC_ID
の値と同じ名前)を作成し、Doxygenが完了したら、ヘルプ出力ディレクトリの内容をcom.yourcompany.yourproject
ディレクトリにコピーします。その後、eclipseを再起動して、新しいプラグインを見つけさせます。
Eclipseヘルププラグインは、Qt compressed helpまたはCHM出力と同様の機能を提供しますが、Eclipseがインストールされて実行されている必要があります。