QDoc設定ファイルの作成

ドキュメントを作成するために、QDocはコンフィギュレーション・ファイル（qdocconf 拡張子）を使ってコンフィギュレーション設定を保存します。

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

QDoc設定ファイル

QDocのコンフィギュレーション設定は1つの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はまた、qhp ファイルに、Qt Help プロジェクトファイルをエクスポートします。このqhpファイルは、qhelpgenerator によって、qch ファイルにドキュメントをパッケージ化するために使用されます。Qt Creator とQt Assistant は、ドキュメントを表示するためにqchファイルを読み込みます。

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

HTMLの設定

QDocにはHTMLジェネレーターがあり、様々な設定を使ってドキュメントのセットをHTMLファイルにエクスポートします。QDocは生成されたドキュメントをoutputdir 変数で指定されたディレクトリに配置します。

outputformats = HTML
outputdir =  <path to output directory>

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

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

HTML.postheader
HTML.postpostheader
HTML.postheader
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 。他のプロジェクトは、そのプロジェクト内のドキュメントにリンクするために、インデックスファイルへの依存関係を定義することができます。

dependesとindexesも参照してください。

マクロとその他の設定

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

macro.pi.HTML         = "Π"

このスニペットコードは、HTMLファイル中の\\pi を&Pi; に置き換えるもので、ブラウザで見たときにギリシャ語のΠ記号として表示されます。

マクロも参照してください。

QMLの追加

QDocはQDocコメントのためにQMLファイルを解析することができます。QDocはQMLの拡張子.qml を持つファイルを解析します。

また、生成されるHTMLファイルにはQDoc設定ファイルで指定されたQMLモジュール名に続く接頭辞と接尾辞をつけることができます。

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

outputprefixes、outputsuffixesも参照してください。