派生プロジェクトのサポート

いくつかの設定変数によって、QDocを使ってQtベースのプロジェクトをサポートすることができます。これは、明示的なリンクコマンドを使わなくても、QDocがクラス参照ドキュメントへのリンクを作成できることを意味します。

説明

description変数は、関連するプロジェクトの短い説明を保持します。

projectも参照してください。

インデックス

indexes 変数は、読み込むインデックス・ファイルのパスのセットを定義する。

indexes = \
    $QT_INSTALL_DOCS/qtcore/qtcore.index \
    $SOME_OTHER_PROJECT/doc/foo.index

indexes 変数はプロジェクトの依存関係を定義するためのdependsに代わるものです。直接パスが提供されるため、QDocを起動する際に-indexdir コマンドラインオプションは必要ありません。

どちらの変数を使っても依存関係を定義できます。Qt ドキュメントはdepends 変数のみを使用します。

depends,project,url も参照してください。

製品名

ドキュメント化される製品の名前がドキュメントの名前と異なる場合、productname 変数を使用します。 projectこれは、複数のドキュメントプロジェクトやモジュールで構成される大規模なドキュメントセットで特に有用です。 \sinceコマンドのような特定のコンテキストで、QDocがプロジェクト名の代わりに製品名を生成できるようになるからです。

例えば、QtではQtを productname 、個々のモジュールではproject 。これによって、作者は \sinceコマンドの略記法を使うことができます。

この設定変数はQt 6.9でQDocに導入されました。

以下も参照してください \since.

プロジェクト

project 変数は、.qdocconf ファイルに関連付けられたプロジェクトの名前を提供する。これはすべてのプロジェクトが設定しなければならない必須の変数である。

プロジェクト名は、関連するプロジェクトのインデックスファイルのファイル名を形成するために使用されます。

project = QtCreator

これにより、qtcreator.index というインデックスファイルが作成されます。

プロジェクト名に空白文字や特殊文字が含まれている場合、生成されるインデックスファイル名ではダッシュ('-')に置き換えられます。

depends、indexes、descriptionも参照してください。

プロジェクトルート

projectroot 変数は、警告ログの相対パス計算のためのプロジェクトのルートディレクトリを設定します。

projectroot = /path/to/project/root

QDocは以下の優先順位でプロジェクト・ルートを決定します：

1. QDOC_PROJECT_ROOT 環境変数
2. projectroot 設定変数
3. どちらも設定されていない場合、絶対パスが使われる

プロジェクトルートが設定されている場合、QDocは警告ログファイルにおいて絶対パスを相対パスに変換します。これにより、異なるビルド環境間でログを移植できるようになります。

Qt のビルドシステムは自動的にQDOC_PROJECT_ROOT を設定するので、通常はprojectroot を手動で設定する必要はありません。

スタンドアロンで QDoc を使用する場合、projectroot を設定すると、ポータブルな警告ログが有効になります：

projectroot = /home/user/myproject
logwarnings = true

projectroot 変数は QDoc 6.11 で導入されました。logwarningsも参照してください。

url

url 変数は現在のプロジェクトに関連するドキュメントのベース URL を保持します。

このURLはプロジェクトの生成されたインデックスファイルに格納されます。インデックスをそれ自身で使うとき、QDocはインデックスにリストされたクラスや関数などへのリンクを構築するときに、これをベースURLとして使います。

project     = QtCore
description = Qt Core Reference Documentation
url         = https://doc.qt.io/qt/

...

これにより、QDocがQt Core モジュール内のエンティティへの参照を生成するときはいつでも、ベースURLはhttps://doc.qt.io/qt/ 。

depends、indexes、url.examplesも参照してください。

url.examples

url.examples 変数は、現在のプロジェクトに関連するサンプルのベースURLを保持します。

もし定義されていれば、サンプルプロジェクトのディレクトリへのリンクが各サンプルドキュメンテーションページの最後に生成されます。url.examples 変数は、このプロジェクトに関連するサンプルのルートディレクトリを参照します。オンラインリポジトリ（http://またはhttps:// で始まる）へのリンク、またはローカルファイルシステム（file:// ）へのリンクにすることができます。

url.examples が定義されていない場合、QDocは代わりにサンプルのファイルとイメージのリストを出力します。

例えば、以下の定義があるとします：

url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/"
examplesinstallpath = corelib

そして、次の \exampleコマンドに対して

/*!
    \example threads/semaphores
    ...
*/

QDocはhttps://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores へのリンクを生成する。

もしURLが例のパスの後にもっと多くの構成要素（例えば、クエリー文字列）を含む場合、\1 をパスのプレースホルダーとして使うことができます：

url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/\1?h=$QT_VER"
examplesinstallpath = corelib

上記と同じ\example コマンドが与えられ、$QT_VER が5.13 に展開されると仮定すると、生成されるURLはhttps://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores?h=5.13 となります。

url.examples 変数はQDocバージョン5.13で導入されました。

url、examplesinstallpath、および \example.

url.sourcesも参照してください。

url.sources 変数は、現在のプロジェクトに関連する C++ ソースコードのベース URL を保持します。これは、例えばgithub.comなどのリポジトリでプロジェクトのソースを見るためのURLです。

ソース・リンクを有効にするには、url.sources.enabled をtrue に設定します。有効にすると、QDoc は、ドキュメント化された各 C++ エンティティのあらすじ（シグニチャ）の宣言へのリンクを、その詳細説明セクションに生成します。

さらに、url.sources.rootdir でソースのルート・ディレクトリーを定義します。生成されるリンクは、ベース URL（url.sources ）と、ソース・ファイルのパス（url.sources.rootdir からの相対パス）で構成されます。

URL にパスの後にさらにコンポーネントが含まれる場合 (分岐を指定するクエリ文字列など)、\1 はパスのプレースホルダとして機能します。同様に、\2 は行番号のプレースホルダとして機能します。

url.sources.linktext は、ソース・リンクのユーザ可視リンク・テキストを設定します。既定では、リンク・テキストは空の文字列です。HTML 出力でリンクをスタイル設定するには、a.srclink CSS セレクタを使用します。

例えば、qtbase/src/gui/doc/qtgui.qdocconf で次のように設定します：

url.sources = "https://code.qt.io/cgit/qt/qtbase.git/tree/\1?h=$QT_VER#n\2"
url.sources.rootdir = ../../..    # root of the `qtbase` repository
url.sources.linktext = "(source)"
url.sources.enabled = true

QDoc は、QT_VER 環境変数で定義されたブランチに固有の、ドキュメント化された C++ エンティティごとにcode.qt.ioへのリンクを生成します。

url.sources 変数は Qt 6.10 で QDoc に導入されました。

usealttextastitle

グラフィカル・ブラウザでレンダリングされた画像に「ツールチップ」を提供することが望ましい場合があります。QDocはこれを実現する方法を提供します。 \imageコマンドにオプションの文字列として与えられたaltテキストは、画像のtitle属性としても使われます。QDocの設定ファイルでこの変数をusealttextastitle = true 。

この設定変数はQt 6.9でQDocに導入されました。

派生プロジェクトのサポート方法

この機能は、Qtリファレンスドキュメントを作成する際にQDocが生成する包括的なインデックスを利用します。

例えば、qtgui.qdocconf（Qt GUI の設定ファイル）には以下の変数定義があります：

project     = QtGui
description = Qt GUI Reference Documentation
url         = http://doc.qt.io/qt/

...

qtgui.index プロジェクト変数名はインデックスファイルのファイル名として使用されます。urlはインデックスファイルに保存されます。その後、QDocはインデックスにリストされたクラスや関数などへのリンクを構築するときに、これをベースURLとして使用します。

depends、indexes、project、urlも参照してください。