支持派生项目

某些配置变量允许您使用 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 命令分配给元素的状态描述符。

默认情况下，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 命令。

例如，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 作为基准 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 设置源文件链接的用户可见链接文本。默认情况下，链接文本为空字符串；请使用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 将为每个已文档化的 C++ 实体生成指向code.qt.io 的链接，这些链接对应于通过QT_VER 环境变量定义的分支。

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。