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ヘルプファイル(.chm)を作成できます。これは、すべてのHTMLファイルを含む単一のファイルであり、検索インデックスも含まれています。多くのプラットフォームでこの形式のビューアがあり、Windowsはネイティブでサポートしています。
これを有効にするには、設定ファイルでGENERATE_HTMLHELPをYES
に設定してください。DoxygenにHTMLヘルプファイルをコンパイルさせるには、HHC_LOCATION設定オプションを使用してHTMLコンパイラ(hhc.exe)へのパスを、CHM_FILEを使用して結果のCHMファイルの名前を指定する必要があります。
この方法の利点は、結果が単一のファイルであり、簡単に配布できることです。また、全文検索も提供します。
欠点は、CHMファイルのコンパイルがWindowsでのみ動作し、MicrosoftのHTMLコンパイラが必要であることですが、これはMicrosoftによってあまり積極的にサポートされていません。このツールはほとんどの人には問題なく動作しますが、時には理由もなくクラッシュすることがあります(よくあることです)。
macOS 10.5以降でDoxygenを実行している場合、Doxygenによって生成されたHTMLファイルから「ドキュメントセット」を作成できます。ドキュメントセットは、HTMLファイルと事前コンパイルされた検索インデックスを含む特殊な構造を持つ単一のディレクトリで構成されます。ドキュメントセットはXcode(Appleが提供する統合開発環境)に組み込むことができます。
ドキュメントセットの作成を有効にするには、設定ファイルでGENERATE_DOCSETをYES
に設定してください。他にもドキュメントセット関連で設定したいオプションがいくつかあります。Doxygenの完了後、HTML出力ディレクトリにMakefileが見つかります。このMakefileで「make install」を実行すると、ドキュメントセットがコンパイルおよびインストールされます。詳細については、この記事を参照してください。
この方法の利点は、Xcode開発環境とうまく統合され、例えばエディタ内の識別子をクリックしてDoxygenドキュメントの対応するセクションにジャンプできることです。
欠点は、macOS上のXcodeとの組み合わせでのみ動作することです。
Qtアプリケーションフレームワークを開発している、またはインストールしたい場合、Qt assistantと呼ばれるアプリケーションが手に入ります。これはQt圧縮ヘルプファイル(.qch
)用のヘルプビューアです。
この機能を有効にするには、GENERATE_QHPをYES
に設定してください。また、QHP_NAMESPACE、QHG_LOCATION、QHP_VIRTUAL_FOLDERなど、他のQtヘルプ関連オプションも入力する必要があります。詳細については、この記事を参照してください。
機能的には、Qt圧縮ヘルプ機能はCHM出力に匹敵しますが、QCHファイルのコンパイルがWindowsに限定されないという追加の利点があります。
欠点は、各ユーザーに対してQt 4.5(またはそれ以降)のセットアップが必要であること、あるいはドキュメントと共にQtヘルプアシスタントを配布することですが、現時点ではこれが独立したパッケージとして利用できないため複雑です。
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圧縮ヘルプやCHM出力と同様の機能を提供しますが、Eclipseがインストールされ、実行されている必要があります。