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

いくつかの設定変数によって、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も参照してください。

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 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 ソース・リンクのユーザー可視リンク・テキストを設定します。デフォルトでは、リンク・テキストは空の文字列です。a.srclink CSS セレクタを使用して、HTML 出力のリンクをスタイル設定します。

例えば、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も参照してください。