検索

Doxygenは、ソースコードにさまざまな方法でインデックスをつけるので、出力を見渡したり、探したりすることが簡単になります。しかし、ブラウジングではなく、キーワードを指定して検索したいこともあります。

HTMLブラウザでは、デフォルトでは、複数ページに渡って検索する機能がありません。ですので、doxygenか外部ツールがこの機能を促進する助けになる必要があります。

doxygenでは、HTML出力に検索機能を追加する７つの方法があります。それぞれ、メリット、デメリットがあります。

1. クライアントサイド検索

検索を可能にする最も簡単な方法は、組込済みのクライアントサイド検索エンジンを使うことです。このエンジンは、JavascriptとDHTMLだけで実装されており、クライアントのブラウザ上で完全に動きます。ですので、追加のツールが必要ありません。有効にするには、設定ファイルのSEARCHENGINE を YES にして、SERVER_BASED_SEARCH を NO にしてください。

もう一つこの方法のメリットは、ライブ検索ができることです。タイプ操作にあわせて検索結果が提示、適応されます。

この方法には欠点もあります。シンボルの検索しかできません。フルテキスト検索機能はありませんし、大規模プロジェクトには適していませんので、検索が遅くなります。

2. サーバーサイド検索

ウェブサーバー上にHTMLドキュメントを配置する計画で、サーバーがPHPコード実行可能であれば、doxygen組込のサーバーサイド検索エンジンを使うこともできます。

有効にするには、設定ファイルで、 SEARCHENGINE と SERVER_BASED_SEARCH を YES　にし、 EXTERNAL_SEARCH を NO にしてください。

クライアントサイド検索エンジンに勝るメリットは、フルテキスト検索ができることと、中規模プロジェクトに向いていることです。

欠点としては、ローカルでは動かない(file:// URLが使えない)ことと、ライブ検索機能がないことです。

覚え書き: 将来、このオプションは次の検索オプションに置き換えられるでしょう。

3. 外部インデックスを使ったサーバーサイド検索

バージョン1.8.3から、サーバーベースの検索オプションを追加しました。doxygenは、このオプションを使って、検索可能な生データを生成し、外部ツールに渡してインデックスと検索をさせることができます。つまり、好みのインデックス・検索エンジンを使えるということです。使いやすいように、doxygenはdoxyindexerというインデックスエンジンと、doxysearch.cgiという検索エンジンを備えています。これらは、Xapian というオープンソースの検索エンジンのライブラリをベースにしています。

この検索方法を可能にするには、SEARCHENGINE, SERVER_BASED_SEARCH, EXTERNAL_SEARCH を YES にします。設定の詳細については、外部インデックスと検索を参照してください。

第2のオプションより優れた点は、この方法はもともと大規模プロジェクトに対応できることです。また、複数のdoxygenプロジェクトと外部データを一つの検索インデックスにまとめることも可能です。検索エンジンとの相互作用によって、ローカルHTMLページからの検索が可能になります。また、検索結果のランキングが良くなり、コンテキストの情報があれば表示されます。

欠点といえば、CGIバイナリを実行できるウェブサーバーが必要で、doxygenを実行した後、追加のインデックス手順を踏まなければなりません。

4. Windows コンパイルHTML Help

Windowsでdoxygenを動かしているのであれば、コンパイルHTMLヘルプ(.chm)を、doxygen作成のHTMLファイルから作れます。これは、すべてのHTMLファイルが入っている単一のファイルで、検索インデックスも含みます。多くのプラットフォームには、この形式のビューワがあり、Windowsはネイティブでサポートしています。

これを可能にするには、設定ファイルの、GENERATE_HTMLHELP を YES にします。doxygenでHTMLヘルプファイルをコンパイルするには、HTMLコンパイラ (hhc.exe) へのパスを、HHC_LOCATION で指定し、CHM_FILE を使って、作るCHMファイルの名前を指定します。

この方法の利点は、単一のファイルなので、配布しやすいことです。フルテキスト検索もできます。

欠点は、CHMファイルのコンパイルがWindowsでしかできないことです。MicrosoftのHTMLコンパイラが必要ですが、Microsoftはそれほど積極的にサポートしていません。ツールは多くの場合良好ですが、原因不明でクラッシュすることがあります。

5. Mac OS X Doc Sets

Mac OS X 10.5以降でdoxygenを動かしているのであれば、doxygenの出力HTMLファイルから、 doc setを作ることができます。doc setは、単一のディレクトリからなっており、特別な構造をもっていて、HTMLファイルにプリコンパイル済みの検索インデックスがつきます。doc setは、Xcode(Apple提供の、統合開発環境)に埋め込むことが可能です。

doc setの作成を可能にするには、設定ファイルで、GENERATE_DOCSET を YES にします。他にも、doc set 関連のオプションはあります。doxygenの実行が終わると、HTML出力ディレクトリには、Makefileができます。"make install" を実行すると、doc setをコンパイルし、インストールします。詳しくはこの章をご覧ください。

この方法の利点は、Xcode開発環境とうまく統合されることです。たとえば、エディターでIDをクリックすると、doxygenドキュメントの適合するセクションに飛んだりします。欠点は、MacOSXのXcodeとの組み合わせでしか動かないことです。

6. Qt Compressed Help

Qtアプリケーションフレームワークをインストール、または開発したいのであれば、Qt assistantを取得してください。Qt Compressed Help ファイル (.qch)のヘルプビューワです。

この機能を有効にするには、GENERATE_QHP を YESにします。 他にも、Qtヘルプ関連のオプションがあるので、設定します。次のオプションです。 QHP_NAMESPACE, QHG_LOCATION, QHP_VIRTUAL_FOLDER.

詳しくは、この文章を参照してください。

いろいろな意味で、Qt Compressed Help機能には、CHM出力と比較すると、QCHファイルのコンパイルがWindowsに制限されないという特別な利点があります。

欠点としては、各ユーザがQt 4.5以上をセットアップする必要があり、また、Qt ヘルプアシスタントとドキュメントを一緒に配布する必要があることです。複雑なことに、これは別パッケージで取得できないようです。

7. Eclipse Help Plugin

Eclipseを使っているのであれば、doxygenが生成したドキュメントを、ヘルププラグインとして埋め込めます。すると、ヘルプブラウザで、ヘルプメニューの"Help contents"から始まるトピックにすることができます。Eclipseでは、はじめてキーワード検索したとき、ドキュメントへの検索インデックスを生成します。

ヘルププラグインを有効にするには、GENERATE_ECLIPSE_HELP を YES にします。そして、自分のプロジェクトのIDを、ECLIPSE_DOC_ID を使って、定義します。次のようにします。

   GENERATE_ECLIPSE_HELP = YES
   ECLIPSE_DOC_ID        = com.yourcompany.yourproject

次に、com.yourcompany.yourproject(ECLIPSE_DOC_IDと同名の) という名のディレクトリを、Eclipseのプラグインディレクトリに作ります。doxygenがヘルプ出力ディレクトリの中身を com.yourcompany.yourproject にコピーし終わるのを待ちます。そしてEclipseを再起動すると、プラグインを認識します。

Eclipseヘルプ・プラグインは、QCHやCHM出力と同様の機能性を提供するのですが、Eclipseのインストールと実行が必要です。

次のセクションに行く / インデックスに戻る