QDoc 設定ファイル

QDoc を実行する前に、QDoc コメントを含むソースファイルの場所を QDoc に指定するための QDoc 設定ファイルを作成する必要があります。設定ファイルへのパス名は、コマンドラインから QDoc に渡されます：

/current/dir$ ../../bin/qdoc ./config.qdocconf

概要

設定ファイルは、「変数 = 値」という形式のエントリのリストです。設定変数を使用することで、QDocが各種ソースファイル、画像、例をどこから読み込むか、生成されたドキュメントをどこに保存するかなどを定義できます。また、設定ファイルにはinclude のようなディレクティブを含めることもできます。例については、minimum.qdocconfを参照してください。

また、設定変数を使用して、QDocに派生プロジェクトのサポートを行わせることもできます。つまり、QDocはプロジェクトのドキュメント内で、Qtのオンラインドキュメント内の要素へのリンクを生成できるようになります。「派生プロジェクトのサポート」のセクションを参照してください。

有効な設定変数名には、大文字、小文字、数字、およびアンダースコア「_」を含めることができます。

設定変数の値は、「=」または「+=」を使用して設定できます。両者の違いは、「=」が以前の値を上書きするのに対し、「+=」は現在の値に新しい値を追加する点です。

一部の設定変数の値は文字列のリストとして解釈されます。例えば： sourcedirs、一方、他の変数は単一の文字列として扱われます。値の文字列を二重引用符で囲むことは任意ですが、囲むことで、値の文字列内で '=' や ' " ' などの特殊文字を使用できるようになります。例えば：

HTML.postheader = "<ul class=\"breadcrumbs\">"

エントリが複数行にわたる場合は、最後の行を除く各行の末尾にバックスラッシュを付けます：

sourcedirs = kernel tools widgets

これは次のように記述できます:

sourcedirs = kernel \
             tools \
             widgets

値が複数行にまたがるが、単一の文字列として解釈される場合、各行はスペースで連結されます。

設定値の展開

QDocは、設定ファイル内での環境変数の展開をサポートしています。たとえば、Qtモジュールは、すべてのQtモジュールドキュメントプロジェクトに関連する定義を含めるために、環境変数QT_INSTALL_DOCSに依存しています:

include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)

展開対象の変数には「$」が接頭辞として付きます。値の文字列内でリテラル文字「$」を使用する場合は、バックスラッシュでエスケープします（「\$」）。

QDoc 6.0 以降、他の設定変数からも値を展開できるようになりました。$variable という構文に加え、${variable} も有効です。後者の方法では、変数名を空白や変数以外の文字で区切る必要がなくなります。例：

baseurl = https://doc.qt.io/
...
url = ${baseurl}qtcreator

ターゲット変数が文字列のリストを指す場合、展開された値ではそれらの文字列がスペースで連結されます:

vars = foo \
       bar \
       baz

items = "Items: $vars"          # Expands to "Items: foo bar baz"

文字列リストの連結に使用する文字を指定することも可能です:

items = "Items: ${vars,|}"      # Expands to "Items: foo|bar|baz"
items = "Items: ${vars,,}"      # Expands to "Items: foo,bar,baz"
items = "Items: ${vars,}"       # Expands to "Items: foobarbaz"

展開はすべての変数が読み込まれた後に実行されるため、変数の定義順序は関係ありません。

環境変数の展開

環境変数を展開する場合、${variable} の構文は$variable とは動作が異なります。前者は変数の内容をその場で展開して設定ファイルの一部として解析しますが、後者は単にその内容を現在の設定変数の値として割り当てるだけです。 これは、環境変数に空白で区切られた要素のリスト、または QDoc が認識するその他の書式が含まれている場合に影響します。

たとえば、環境変数 `SRCDIRS ` の値が `"../src/a ../src/b"` である場合、

sourcedirs  = $SRCDIRS      # Fail - value is interpreted as a single path.
sourcedirs  = ${SRCDIRS}    # Ok - whitespace is used as a delimiter.

設定変数

変数リスト

• は
• depends
• ヘッダー内のドキュメント
• 例ディレクトリ
• examples
• examplesinstallpath
• examples.fileextensions
• examples.warnaboutmissingimages
• examples.warnaboutmissingprojectfiles
• 除外ディレクトリ
• 除外ファイル
• 追加画像
• 虚偽
• ヘッダーディレクトリ
• ヘッダー
• ヘッダーのファイル拡張子
• HTML.footer
• HTML.postheader
• HTML.postpostheader
• HTML.style
• インクルードパス
• includeprivate
• ignorewords
• ignoresince
• imagedirs
• imagesoutputdir
• indexes
• language
• locationinfo
• logwarnings
• macro
• manifestmeta
• モジュールヘッダー
• navigation
• outputdir
• 出力形式
• 出力プレフィックス
• 出力サフィックス
• parsecppcomments
• preliminary
• productname
• project
• projectroot
• 自動生成されたドキュメントを表示
• ソースディレクトリ
• sources
• sources.fileextensions
• spurious
• タブサイズ
• url
• URLの例
• url.sources
• 代替テキストをタイトルとして使用
• バージョン
• versionsym
• warninglimit

カテゴリ

• 汎用設定変数
• フォーマット固有の設定変数

設定ファイルの例

• 最小限の設定ファイル:minimum.qdocconf
• Qtの設定ファイル:qtgui.qdocconf