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

一部の設定変数を使用することで、QDoc を利用して Qt ベースのプロジェクトをサポートすることができます。これにより、プロジェクトにオンラインの Qt ドキュメントへのリンクを含めることが可能になり、明示的なリンクコマンドを実行しなくても、QDoc がクラスリファレンスドキュメントへのリンクを作成できるようになります。

説明

description変数には、関連するプロジェクトの簡単な説明が格納されます。

「project」も参照してください。

インデックス

indexes 変数は、読み込むインデックスファイルへのパス群を定義します。

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

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

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

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

暫定版

preliminary 変数を使用して、 \preliminary コマンドを使用して要素に割り当てられるステータス記述子をカスタマイズするには、xml-ph-0000@deepl.internal変数を使用します。

デフォルトでは、QDocはAPIリファレンス内でこれらの要素にPreliminary 記述子を付与し、メッセージを生成します

「この <要素タイプ> は開発中であり、変更される可能性があります。」というメッセージを生成します。

このメッセージは、要素のドキュメント本文内に表示されます。QDocは、上記のメッセージ内の<element type>を、その型（例：「module」、「function」、または「class」）に置き換えます。

カスタムステータス記述子を使用するには、preliminary 変数を定義します：

preliminary = "Technology preview"

カスタムステータスメッセージを使用するには、preliminary.description サブ変数も定義します:

preliminary = "Technology preview"
preliminary.description = "This \1 is in technology preview and is subject to change."

説明文にプレースホルダー「\1 」が含まれている場合、QDoc はそれを要素タイプに置き換えます。

preliminary 変数は、Qt 6.12でQDocに導入されました。

productname

ドキュメント化対象の製品名がドキュメントの名前と異なる場合は、productname 変数を使用してください project これは、複数のドキュメントプロジェクトやモジュールで構成される大規模なドキュメントセットで特に有用です。これにより、QDoc は、 \since コマンドなど、特定の状況において、QDocがプロジェクト名ではなく製品名を生成できるようになるため、特に複数のドキュメントプロジェクトやモジュールで構成される大規模なドキュ

たとえば、Qt ではQt を productname として定義していますが、個々のモジュールはそれぞれ独自のproject 名を定義しています。これにより、作成者は \since コマンドの省略形表記を使用できるようになります。

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

関連項目 \since。

プロジェクト

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

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

project = QtCreator

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

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

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

projectroot

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 コマンドにオプションの文字列として指定された代替テキストが、画像のtitle属性としても使用されます。QDoc 設定ファイルでこの変数をusealttextastitle = true に設定することで、この動作を有効にできます。

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

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

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

たとえば、qtgui.qdocconf（Qt GUI 用の設定ファイル）には、次のような変数定義が含まれています：

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

...

プロジェクト変数name は、インデックスファイルのファイル名を形成するために使用されます。この場合、qtgui.index ファイルが作成されます。urlはインデックスファイルに保存されます。その後、QDoc は、インデックスにリストされているクラス、関数、その他の項目へのリンクを構築する際、これをベース URL として使用します。

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