出力のカスタマイズ

Doxygenは、さまざまなレベルのカスタマイズを提供します。見栄えの変更セクションでは、出力の見栄えを少し変える方法を説明します。 Layout セクションでは、ページ上の情報の順序を変えたり隠す方法を説明します。XML出力を使うセクションでは、Doxygen が作り出すXML出力をベースに、好きな出力を生成する方法を説明します。

見栄えの変更

以降のサブセクションでは、少ない努力で変えられる箇所を説明します。

全体色

HTML出力の全体色を変える方法に、次の3つのオプションがあります。

順に、色調、彩度、ガンマ補正です。

便利なツールとして、GUIツール Doxywizardには、これらオプションの値を変えてその効果をリアルタイムに確認できるコントロールがついています。

動的な内容

HTML出力をさらにインタラクティブにするために、デフォルトでは無効のオプションがたくさんあります。

HTML_DYNAMIC_SECTIONS オプションを有効にすると、HTMLのグラフのような内容をデフォルトでは隠して、読む人がこれらのセクションを展開できるようになります。
HAVE_DOT と INTERACTIVE_SVG を有効にし、DOT_IMAGE_FORMAT を svg にすれば、SVGイメージをdoxygenが作ります。SVGイメージによって、ユーザーはズームやパン(ただしこれは、イメージのサイズがあるサイズを超えたときにしか起こりません)ができます。

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

フォントやカラー、マージンなど、HTML 出力の見栄えを細かく変えるには、カスケーディング・スタイル・シートを変えます。 doxygenが生成するHTMLページに対して、独自のヘッダやフッタをdoxygenに採用させることも可能です。例えば、自分のウェブサイトのスタイルに出力を適合させることが可能です。

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

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

これで、3つのファイルができます。

header.html は、通常HTMLページの始まりを示すのに使う HTML断片です。この断片は、body タグで終わり、body タグは $word といった形の1対のコマンドを含みます。これらは、Doxygenによって置き換えられます。
footer.html は、通常HTMLページの終わりを示すのに使う HTML断片です。ここでも特殊コマンドを使えます。このファイルには、www.doxygen.org へのリンクと、bodyとhtmlの終了タグが含まれます。
customdoxygen.css は、Doxygenが使うデフォルトのカスケーディング・スタイル・シートです。このファイルは見るだけにして、書き換えた内容は、別のスタイルシートに入れて、ファイル名を HTML_EXTRA_STYLESHEET に指定してください。

これらのファイルを編集し、設定ファイルから参照できるようにしてください。

HTML_HEADER = header.html
HTML_FOOTER = footer.html
HTML_EXTRA_STYLESHEET = my_customdoxygen.css

覚え書き: HTML_STYLESHEETを使うことは、もはや勧められません。doxygenを新しいバージョンにアップグレードするのが難しくなるからです。代わりに、HTML_EXTRA_STYLESHEETを使ってください。

カスタムヘッダ内で使えるメタコマンドの詳細は、HTML_HEADERタグのドキュメントを見てください。

覚え書き: HTML出力ディレクトリにスタイル・シートのファイルを置かないでください。ソースファイルとして扱ってください。Doxygenがコピーします。; カスタムヘッダにイメージなどの外部コンテンツを使用する場合は、HTML出力ディレクトリに配置されるように自分で仕組んでください。例えば、Doxygenを起動するスクリプトでコピーするなどです。

警告: ヘッダやフッタの構造は、doxygenをアップグレードすると変わる可能性がありますので、カスタマイズしたヘッダやフッタを使う場合は、アップグレードした後、有効な出力をするとは限りません。

ページレイアウトの変更

出力の構成を変えたい場合もあるでしょう。スタイル・シートやヘッダ、フッタを変えてもこれには対応できません。

これには、レイアウトファイルを編集します。Doxygenは、どの情報をどの順序で提示するか、またどのように提示するかもある程度制御します。レイアウトファイルはXML形式です。

デフォルトのレイアウトファイルは、次のコマンドで生成します。

doxygen -l

レイアウトファイルの名前を指定することもできます。省略すると、DoxygenLayout.xml です。

次のステップは、設定ファイル内で、

LAYOUT_FILE = DoxygenLayout.xml

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

ファイルのトップレベルは、以下のような構造です。

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

XMLのルート・タグは、doxygenlayout で、version という属性がついています。これは、将来、バックワード・コンパティブルでない変更に対応するために、使います。

最初のセクションの navindex は、各HTMLページのトップに表示されるナビゲーションタブのレイアウトに対応します。同時に、GENERATE_TREEVIEWが有効のときは、navindex はナビゲーションツリーの項目も制御します。各タブは、XMLファイル内の tab タグに対応します。

タブは、visible 属性を no にすれば隠せます。タブのタイトルは、title を指定することで変えられます。タイトルが空(デフォルト)であれば、Doxygenが指定言語に対応したタイトルで埋めます。

タブ順序を変えるには、navindex 要素内で、XML ファイル内のタブ要素を移動します。また、ツリー構造を変えることもできます。ただし、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>

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

デフォルトで、ナビゲーションツリーにおけるusergroupエントリは、グループのコンテンツのあるランディングページへのリンクです。url 属性を使えば、違ったページへのリンクをすることもできます。<tab> 要素にできるのと同様です。また、url="[none]" を使えば、リンクを一切避けることもできます。つまり、以下のように。

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

navindex の後の要素は、Doxygenが生成するさまざまなページのレイアウトに対応します。

class 要素は、ドキュメントつきクラス、共用体、インタフェース用に生成される全ページのレイアウトを表わします。
namespace 要素は、ドキュメントつき名前空間(及びJavaパッケージ)用に生成される全ページのレイアウトを表わします。
file 要素は、ドキュメントつきファイル用に生成される全ページのレイアウトを表わします。
group 要素は、ドキュメントつきグループ(またはモジュール)用に生成される全ページのレイアウトを表わします。
directory 要素は、ドキュメントつきディレクトリ用に生成される全ページのレイアウトを表わします。

上記ページ要素のうち一つに含まれるXMLタグそれぞれが、一定の情報を表わします。どんなタイプのページにも含まれる情報もあれば、特殊なタイプのページにしか含まれない情報もあります。Doxygenは、XMLファイルに出現する順序で情報を並べます。

どのページにも出現しうる一般的な要素を次に掲げます。

briefdescription: ページの要約説明
detaileddescription: ページの詳細説明
authorsection: ページの中の著者のセクション(manページでしか使用しません)
memberdecl: ページにおけるメンバーの簡単な概略(メンバー宣言)。この要素には、メンバーリストのタイプごとに子要素があります。出現しうる子要素は、詳細にはドキュメントにリストアップされません。しかし要素の名前によって、その要素が表わすメンバータイプがわかるはずです。
memberdef: ページにおける詳細なメンバーリスト(メンバー定義)。 memberdecl 要素と同様、この要素にも子要素がたくさんありえます。

クラスページには、次のような特別な要素があります。

includes: このクラスの定義を得るのに必要なインクルードファイル。
inheritancegraph: クラスの継承関係。CLASS_DIAGRAMオプションは、継承関係が基底クラスと派生クラスのリストか、あるいは図かを決定します。
collaborationgraph: クラスのコラボレーション図。
allmemberslink: クラスの全メンバーのリストへのリンク。
usedfiles: クラスのドキュメントを抽出したもとのファイルのリスト。

ファイルページには、次のような特別な要素があります。

includes: このファイルに含まれる #include 文のリスト。
includegraph: ファイルのinclude依存関係図。
includedbygraph: ファイルのinclude被依存関係図。
sourcelink: このファイルのソースコードへのリンク。

グループページには、groupgraph 要素が特別にあり、グループ間の依存関係を示す図を表わします。

同様に、ディレクトリページには directorygraph 要素があり、ディレクトリ間の依存関係を示す図を表わします。これは、ディレクトリ内にあるファイルの#include 関係に基づいています。

要素によっては、visible 属性があり、出力から隠すのに使えます。隠すには、その属性値を "no" にします。また、設定オプションの値を使って、隠すかどうかを設定することも可能です。これには、$記号を名前の前につけます。たとえば、次のように。

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

この方法を加えた主目的は、以前の方式を使えるようにするためです。 visible 属性は、doxygenにとってヒントでしかありません。 yes に設定されていても、関連する情報がなければ、それは省略されます(つまり、空のセクションは生成されません)。

title 属性をもつタグがあります。この属性は、doxygenが情報のヘッダとして使うタイトルをカスタマイズするのに使います。

警告: 　情報を隠すためと思って、レイアウトファイルから要素を取り除いてはいけません。取り除くと、生成される出力内のリンクが壊れてしまいます。

XML出力を使う

上記2つの方法でも融通が効かない場合、doxygenが作るXML出力を使うこともできます。GENERATE_XMLをYESにすれば出力されます。

XML出力は、インデックスファイル index.xml と、その他の XML ファイルとで構成されます。indexはdoxygenが抽出したすべての要素をリストアップしたファイルです。他のXMLファイルで詳細が参照できます。インデックスの構造は、スキーマファイル index.xsd に記載されます。他のXMLファイルはすべて、スキーマファイル compound.xsd に記載されます。一まとめのXMLファイルのほうがよければ、combine.xslt を使って、インデックスと他のファイルを結合できます。

ファイルを解析するには、XMLパーサーならなんでもいいですが、doxygenのソース配布版にある addon/doxmlparser ディレクトリにあるパーサーも使えます。パーサーのインターフェースについては addon/doxmlparser/include/doxmlintf.h を、例については addon/doxmlparser/example を見てください。

doxmlparserを使う利点は、インデックスファイルをメモリーに読み込み、あとはユーザがインデックスを探索するうちに、暗黙のうちに必要なXMLファイルのみロードする点です。その結果、すべてのXMLファイルを大きなDOMツリーに読み込むことではメモリーに収まりきらないような、非常に大きなプロジェクトでも使えます。

doxygenのXML出力を使った例について、Breathe プロジェクトを参照してください。これは、Pythonが提供し、Sphinxドキュメント生成ツールとのブリッジをします。

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

目次