QDoc設定ファイルの作成

ドキュメントを生成するために、QDocは設定情報を保存するqdocconf 拡張子の設定ファイルを使用します。

「QDoc 設定ファイル」の記事では、さまざまな設定変数についてより詳しく解説しています。

QDoc 設定ファイル

QDocの設定は、単一のqdocconfファイルに記述することもできますが、他の qdocconf ファイルに記述することも可能です。include(<filepath>) コマンドを使用すると、設定ファイル内で他の設定ファイルをインクルードすることができます。

QDocには、HTMLドキュメントとDocBook XML形式のドキュメントという2種類の出力形式があります。 これら2つの出力の主な違いは、HTMLドキュメントの場合、設定ファイルにHTMLのスタイル情報を記述する必要があるのに対し、DocBookドキュメントの場合はその必要がなく、後から別のプロセスでDocBookドキュメントのスタイルを設定できる点にあります。そのため、DocBookの方が同じ情報に対して異なるスタイルを適用できる点で柔軟性が高くなります。

QDoc を実行するには、プロジェクト設定引数を引数として指定します。

qdoc project.qdocconf

プロジェクト設定ファイルには、QDocがドキュメントを作成するために使用する情報が含まれています。

プロジェクト情報

QDocは、project の情報を使用してドキュメントを生成します。

project = QDoc Project
description = Sample QDoc project

入力および出力ディレクトリ

ソースディレクトリへのパスを指定することで、QDocはソースを検索し、ドキュメントを生成することができます。

sourcedirs = <path to source code>
exampledirs = <path to examples directory>
imagedirs = <path to image directory>

sources.fileextensions = "*.cpp *.qdoc *.mm *.qml"
headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx"
examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml"
examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng"

QDocは、fileextensions 変数で指定されたヘッダーおよびソースファイルを処理します。

同様に、QDocには出力ディレクトリへのパスも必要です。outputformats 変数は、ドキュメントの種類を決定します。ドキュメントのビルドをモジュール化するため、これらの変数は別々の設定ファイルに記述する必要があります。

outputdir  =    $SAMPLE_PROJECT/doc/html
outputformats = HTML

QDocは、qdocconfファイルや環境変数に対する相対パスも解決できます。

追加ファイル

QDocは、生成されたドキュメントを出力ディレクトリで指定されたディレクトリに出力します。また、QDocがエクスポートすべき追加ファイルを指定することも可能です。

HTML.extraimages = extraImage.png \
                   extraImage2.png

extraImage.png およびextraImage2.png ファイルは、HTML出力ディレクトリにコピーされます。

Qt Help フレームワークの設定

QDocは、Qt Help プロジェクトファイルを、qhp ファイルとしてエクスポートします。このqhpファイルは、qhelpgenerator によってドキュメントをqch ファイルにパッケージ化する際に使用されます。Qt Creator およびQt Assistant は、qchファイルを読み込んでドキュメントを表示します。

「ヘルププロジェクトファイルの作成」の記事では、設定オプションについて解説しています。

HTMLの設定

QDocには、さまざまな設定オプションを用いて一連のドキュメントをHTMLファイルとしてエクスポートするHTMLジェネレータが搭載されています。QDocは、生成されたドキュメントをoutputdir 変数で指定されたディレクトリに配置します。

outputformats = HTML
outputdir =  <path to output directory>

QDocは、HTMLを生成するためのスタイルやテンプレートがどこにあるかを把握する必要があります。通常、テンプレートディレクトリには、スクリプトやCSSファイルを含むscripts 、images 、およびstyle ディレクトリが含まれています。

主な設定変数は以下の通りです：

HTML.postheader
HTML.postpostheader
HTML.footer

HTML.headerstyles
HTML.stylesheets = template/style/style.css \
                   template/style/style1.css

HTML.scripts = template/scripts/script.js

HTML.headerstyles 変数はHTMLファイルにスタイル情報を挿入し、HTML.stylesheets はQDocが出力ディレクトリにコピーすべきファイルを指定します。さらに、QDocはpostheader 、footer 、および関連する変数に含まれる文字列を各HTMLファイルに埋め込みます。

「フォーマット固有の設定変数」の記事では、各変数の使用方法について概説しています。

QDoc インデックスファイル

ドキュメントプロジェクトは、一連の依存関係を指定するか、またはそのプロジェクトが依存するインデックスファイルへの一連の直接パスを指定することで、他のプロジェクト内のターゲットにリンクすることができます。QDocがプロジェクトのドキュメントを生成する際、そのプロジェクト内のリンク可能な各エンティティへのURLを含む.index ファイルも生成します。 他のプロジェクトでは、そのプロジェクト内のドキュメントにリンクするために、インデックスファイルへの依存関係を定義することができます。

関連項目:dependsおよびindexes。

マクロおよびその他の設定

HTML文字を置換するためのマクロが存在し、特定のHTML有効な文字を生成するのに役立ちます。

macro.pi.HTML         = "Π"

このコードスニペットは、HTMLファイル内の「\\pi 」という記述をすべて「&Pi 」に置換します。これにより、ブラウザで表示された際にギリシャ文字の「Π」として表示されます。

関連項目： マクロ。

QML の追加機能

QDocは、QMLファイルからQDocコメントを解析することができます。QDocは、ファイル拡張子変数（fileextensions）にその拡張子タイプが含まれている場合、QML拡張子を持つファイル（.qml ）を解析します。

また、生成される HTML ファイルには、QDoc 設定ファイルで指定された、QML モジュール名の後にプレフィックスやサフィックスを付加することができます。

outputprefixes = QML
outputprefixes.QML = uicomponents-
outputsuffixes = QML
outputsuffixes.QML = -tp

関連項目:outputprefixes、outputsuffixes。