ドキュメント 変更履歴 拡張機能 例  
出力のカスタマイズ

目次

Doxygenは様々なレベルのカスタマイズを提供します。微調整のセクションでは、出力の見た目を微調整したい場合の対処法について説明しています。レイアウトのセクションでは、ページ上の特定の情報を並べ替えたり非表示にしたりする方法について説明しています。XML出力のセクションでは、Doxygenによって生成されたXML出力に基づいて、必要な出力を生成する方法について説明しています。

微調整

次のサブセクションでは、少しの労力で調整できるいくつかの側面について説明します。

全体的な色

HTML出力の全体的な色を変更するために、Doxygenは3つのオプションを提供しています。

それぞれ、色の色相、彩度、ガンマ補正を変更します。

便宜上、GUIフロントエンドのDoxywizardには、これらのオプションの値を変更した場合の出力をリアルタイムで確認できるコントロールがあります。

ナビゲーション

デフォルトでは、Doxygenはページ全体にわたるタイトル領域を表示し、その下に各HTMLページの左側にナビゲーションツリーをサイドバーとして配置します。

これはDoxyfileの以下の設定に対応します。

サイドバーをページ全体の高さに広げるには、次のようにします。

ナビゲーションツリーを、各HTMLページの上部にあるタブに置き換えることもできます。これは以下の設定に対応します。

または、両方のナビゲーション形式を使用することもできます。

これはサイドバーが全高にわたる場合でも機能します。

外部インデックスをすでに使用している場合（つまり、GENERATE_HTMLHELP、GENERATE_ECLIPSEHELP、GENERATE_QHP、またはGENERATE_DOCSETのいずれかのオプションを有効にしている場合）、次のようにすべてのインデックスを無効にすることもできます。

動的コンテンツ

HTML出力をよりインタラクティブにするために、Doxygenはデフォルトで無効になっているいくつかのオプションを提供しています。

  • HTML_DYNAMIC_SECTIONSを有効にすると、DoxygenはHTML内の特定のコンテンツ（グラフなど）をデフォルトで非表示にし、読者の要求に応じてこれらのセクションを展開できるようにします。
  • HAVE_DOTをINTERACTIVE_SVGと共に有効にし、DOT_IMAGE_FORMATをsvgに設定すると、DoxygenはユーザーがズームやパンできるSVG画像を生成します（これは画像のサイズが特定のサイズを超えた場合にのみ発生します）。

ヘッダー、フッター、スタイルシートの変更

HTML出力のフォントや色、マージン、その他の見た目を詳細に調整するには、異なるカスケーディングスタイルシートを作成できます。また、Doxygenに各HTMLページにカスタムヘッダーとフッターを使用させることもできます。例えば、出力をウェブサイトの残りの部分で使用されているスタイルに合わせる場合などです。

これを行うには、まずDoxygenを次のように実行します。

doxygen -w html header.html footer.html customdoxygen.css

これにより、3つのファイルが作成されます。

  • header.htmlは、Doxygenが通常HTMLページを開始するために使用するHTMLフラグメントです。このフラグメントはbodyタグで終わり、$wordという形式のいくつかのコマンドが含まれていることに注意してください。これらはDoxygenによってその場で置き換えられます。
  • footer.htmlは、Doxygenが通常HTMLページを終了するために使用するHTMLフラグメントです。ここでも特殊なコマンドを使用できます。このファイルには、www.doxygen.orgへのリンクと、bodyおよびhtmlの終了タグが含まれています。
  • customdoxygen.cssは、Doxygenが使用するデフォルトのカスケーディングスタイルシートです。このファイルを参照するだけで、独自のスタイルシートにいくつかの設定を上書きし、それらの追加ファイルをHTML_EXTRA_STYLESHEETを介して参照することをお勧めします。

これらのファイルを編集し、設定ファイルから参照する必要があります。

注
Doxygenの新しいバージョンへのアップグレードを困難にするため、HTML_STYLESHEETの使用は推奨されなくなりました。代わりにHTML_EXTRA_STYLESHEETを使用してください。

カスタムヘッダー内で使用できるメタコマンドの詳細については、HTML_HEADERタグのドキュメントを参照してください。

注
スタイルシートをHTML出力ディレクトリに配置しないでください。ソースファイルとして扱ってください。Doxygenがそれをコピーします。
カスタムヘッダーで画像やその他の外部コンテンツを使用する場合、それらがHTML出力ディレクトリに適切に配置されるように、Doxygenを実行してから画像をコピーするスクリプトを作成するなどして、自分で管理する必要があります。
警告
Doxygenの新しいバージョンにアップグレードすると、ヘッダーとフッターの構造が変更される場合があります。そのため、カスタムヘッダーまたはフッターを使用している場合、アップグレード後に有効な出力を生成できなくなる可能性があります。

ページのレイアウトの変更

場合によっては、出力の構造を変更したいことがあります。そのような場合、別のスタイルシートやカスタムヘッダー、フッターは役に立ちません。

Doxygenが提供する解決策はレイアウトファイルです。これを変更することで、Doxygenが表示する情報、その順序、そしてある程度の表示方法を制御できます。レイアウトファイルはXMLファイルです。

デフォルトのレイアウトは、以下のコマンドを使用してDoxygenによって生成できます。

doxygen -l

オプションでレイアウトファイル名を指定できます。省略された場合はDoxygenLayout.xmlが使用されます。

次のステップは、設定ファイルでレイアウトファイルに言及することです（LAYOUT_FILEも参照）。

LAYOUT_FILE = DoxygenLayout.xml

レイアウトを変更するには、レイアウトファイルを編集するだけです。

ファイルのトップレベル構造は次のようになります。

<doxygenlayout version="1.0">
  <navindex>
    ...
  </navindex>
  <class>
    ...
  </class>
  <namespace>
    ...
  </namespace>
  <concept>
    ...
  </concept>
  <file>
    ...
  </file>
  <group>
    ...
  </group>
  <directory>
    ...
  </directory>
</doxygenlayout>

XMLファイルのルート要素はdoxygenlayoutで、versionという名前の属性を持ちます。これは将来、下位互換性のない変更に対応するために使用されます。

navindex要素によって識別される最初のセクションは、各HTMLページの上部に表示されるナビゲーションタブのレイアウトを表します。GENERATE_TREEVIEWが有効な場合、同時にナビゲーションツリー内の項目も制御します。各タブは、XMLファイルのtab要素で表されます。

visible属性をnoに設定することで、タブを非表示にできます。また、title属性の値として指定することで、タブのデフォルトのタイトルを上書きすることもできます。タイトルフィールドが空の文字列（デフォルト）の場合、Doxygenは適切な言語固有のタイトルを埋め込みます。

XMLファイルのnavindex要素内でタブ要素を移動することでタブの順序を変更したり、ツリー構造を変更したりすることもできます。ただし、type属性の値は変更しないでください。サポートされているのは固定された種類の型のみで、それぞれが特定のインデックスへのリンクを表します。

「user」という名前の型を使用してカスタムタブを追加することもできます。以下は、www.google.comを指す「Google」というタイトルのタブを追加する方法の例です。

  <navindex>
    ...
    <tab type="user" url="http://www.google.com" title="Google"/>
    ...
  </navindex>

URLフィールドは相対URLでも構いません。URLが@refで始まる場合、リンクはクラス、関数、グループ、関連ページなどの文書化されたエンティティを指します。@pageを使用してmypageというラベルでページを定義したとすると、このページへの「My Page」というラベルのタブは次のようになります。

  <navindex>
    ...
    <tab type="user" url="@ref mypage" title="My Page"/>
    ...
  </navindex>

「usergroup」という型のタブを使用して、タブをカスタムグループにまとめることもできます。以下の例では、上記のタブを「My Group」というタイトルのユーザー定義グループに入れています。

  <navindex>
    ...
    <tab type="usergroup" title="My Group">
      <tab type="user" url="http://www.google.com" title="Google"/>
      <tab type="user" url="@ref mypage" title="My Page"/>
    </tab>
    ...
  </navindex>

グループは階層を形成するためにネストできます。

デフォルトでは、ナビゲーションツリーのユーザーグループエントリは、グループの内容を含むランディングページへのリンクです。url属性を使用して、<tab>要素と同様に別のページにリンクしたり、url="[none]"を使用してリンクを禁止したりできます。つまり、

   <tab type="usergroup" title="Group without link" url="[none]">
   ...
   </tab>

navindexの後の要素は、Doxygenによって生成される様々なページのレイアウトを表します。

  • class要素は、ドキュメント化されたクラス、構造体、共用体、インターフェースに対して生成されるすべてのページのレイアウトを表します。
  • namespace要素は、ドキュメント化された名前空間（およびJavaパッケージ）に対して生成されるすべてのページのレイアウトを表します。
  • concept要素は、ドキュメント化されたコンセプトに対して生成されるすべてのページのレイアウトを表します。
  • module要素は、ドキュメント化されたC++モジュールに対して生成されるすべてのページのレイアウトを表します。
  • file要素は、ドキュメント化されたファイルに対して生成されるすべてのページのレイアウトを表します。
  • group要素は、ドキュメント化されたグループ（またはトピック）に対して生成されるすべてのページのレイアウトを表します。
  • directory要素は、ドキュメント化されたディレクトリに対して生成されるすべてのページのレイアウトを表します。

上記のページ要素内の各XML要素は、特定の情報の一部を表します。一部のピースは各タイプのページに表示できますが、他のピースは特定のタイプのページに固有です。Doxygenは、XMLファイルに表示される順序でピースをリストします。

各ページで以下の一般的な要素が可能です。

briefdescription
ページ上の簡単な説明を表します。
detaileddescription
ページ上の詳細な説明を表します。

directoryページを除く各ページで以下の汎用要素が可能です。

authorsection
ページの著者セクションを表します（マニュアルページにのみ使用されます）。これはマニュアルページの個別のセクションであり、My ProjectのソースコードからDoxygenによって自動生成されました。のようなテキストが含まれます。これは、詳細な説明の中に著者段落を生成するDoxygenコマンド\authorまたは\authorsと混同すべきではありません。

conceptページを除く各ページで以下の汎用要素が可能です。

memberdecl
ページ上のメンバーの簡単な概要（メンバー宣言）を表します。この要素は、メンバーリストのタイプごとに子要素を持ちます。可能な子要素はドキュメントには詳細にリストされていませんが、要素の名前は、その要素が表すメンバーのタイプを示す良いヒントになるはずです。

conceptおよびmoduleページを除く各ページで以下の汎用要素が可能です。

memberdef
ページ上の詳細なメンバーリスト（メンバー定義）を表します。memberdecl要素と同様に、この要素にもいくつかの可能な子要素があります。

classページには以下の固有の要素があります。

includes
このクラスの定義を取得するために必要なインクルードファイルを表します。
inheritancegraph
クラスの継承関係を表します。CLASS_GRAPHオプションによって、継承関係が基底クラスと派生クラスのリストであるか、グラフであるかが決まることに注意してください。
collaborationgraph
クラスのコラボレーショングラフを表します。
allmemberslink
クラスのすべてのメンバーのリストへのリンクを表します。
usedfiles
クラスのドキュメントが抽出されたファイルのリストを表します。

conceptページには以下の固有の要素があります。

includes
このクラスの定義を取得するために必要なインクルードファイルを表します。
definition
概念の定義を表します。

fileページには以下の固有の要素があります。

includes
このファイルに含まれる#include文のリストを表します。
includegraph
ファイルのインクルード依存関係グラフを表します。
includedbygraph
ファイルのインクルード元依存関係グラフを表します。
sourcelink
このファイルのソースコードへのリンクを表します。

moduleページには、このモジュールからエクスポートされるモジュールを表す特定のexportedmodules要素があります。

groupページには、グループ間の依存関係を示すグラフを表す特定のgroupgraph要素があります。

同様に、directoryページには、ディレクトリ内のファイルの#include関係に基づいて、ディレクトリ間の依存関係を示すグラフを表す特定のdirectorygraph要素があります。

一部の要素にはvisible属性があり、この属性の値をnoに設定することで、生成された出力からそのフラグメントを非表示にすることができます。設定オプションの値を使用して可視性を決定することもできます。その場合、オプション名の前にドル記号を付けます。例：

  ...
  <includes visible="$SHOW_INCLUDE_FILES"/>
  ...

これは主に下位互換性のために追加されました。visible属性はDoxygenへのヒントにすぎないことに注意してください。特定のピースに関連する情報がない場合、たとえyesに設定されていても省略されます（つまり、空のセクションは生成されません）。
すべての要素にレイアウトファイルにvisible属性が表示されているわけではありませんが、この属性はとにかく使用できます（デフォルトはvisible="yes"です）。

一部の要素にはtitle属性があります。この属性は、Doxygenがそのピースのヘッダーとして使用するタイトルをカスタマイズするために使用できます。

Doxygenバージョン1.13.1以降およびレイアウトバージョン2.0以降、Doxygenはユーザー定義のレイアウトファイルで欠落している要素にデフォルト値を挿入することに注意してください。これにより、新しい要素を導入しても、ユーザー定義のレイアウトファイルを更新してそれらを表示する必要がなくなります。古いDoxygenまたはレイアウトバージョンでは、欠落している要素は非表示として扱われます。

XML出力の使用

上記の2つの方法でも十分な柔軟性が得られない場合、Doxygenによって生成されたXML出力をベースとして、好きな出力を生成することもできます。これを行うには、GENERATE_XMLをYESに設定します。

XML出力は、Doxygenによって抽出されたすべての項目を詳細な他のXMLファイルへの参照とともにリストするindex.xmlという名前のインデックスファイルで構成されます。インデックスの構造は、スキーマファイルindex.xsdで記述されています。他のすべてのXMLファイルは、compound.xsdという名前のスキーマファイルで記述されています。大きなXMLファイルを1つにしたい場合は、XSLTファイルcombine.xsltを使用してインデックスと他のファイルを結合できます。

ファイルを解析するには任意のXMLパーサーを使用できます。または、Doxygenのソース配布のaddon/doxmlparserディレクトリにあるものを使用することもできます。パーサーのインターフェースについては、addon/doxmlparser/doxmlparser/index.pyとaddon/doxmlparser/doxmlparser/compound.pyを参照してください（これはgeneratedDSによって生成され、templates/xmlにあるXMLスキーマファイルindex.xsdとcompound.xsdに従っています）。例については、addon/doxmlparser/examplesを参照してください。

doxmlparserを使用する利点は、インデックスファイルのみをメモリに読み込み、その後、インデックスを介して暗黙的に読み込むXMLファイルのみを読み込むことができることです。その結果、すべてのXMLファイルを1つの大きなDOMツリーとして読み込むとメモリに収まらないような非常に大規模なプロジェクトでも機能します。

Doxygen XML出力をPythonから使用して、Sphinxドキュメントジェネレーターと連携させる例については、Breatheプロジェクトを参照してください。

次のセクションに進むか、インデックスに戻ります。