支持派生项目

某些配置变量允许您使用 QDoc 来支持基于 Qt 的项目。它们允许你的项目包含指向在线 Qt 文档的链接，这意味着 QDoc 能够创建指向类参考文档的链接，而无需任何显式链接命令。

描述

description 变量包含对相关项目的简短描述。

另请参阅项目。

索引

indexes 变量定义了一组要加载的索引文件的路径。

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

indexes 变量为定义项目的依赖关系提供了一种替代依赖关系的方法。由于提供了直接路径，调用 QDoc 时不需要-indexdir 命令行选项。

使用任一变量都可以定义依赖关系。Qt XML 文档只使用depends 变量。

另请参阅depends、project和url。

产品名称

如果文档中的产品名称与文档名称不同，请使用productname 变量。 project这对由多个文档项目和/或模块组成的大型文档集特别有用，因为它允许 QDoc 在某些情况下生成产品名称而不是项目名称，如 \since命令。

例如，Qt 将Qt定义为productname ，而每个单独的模块则定义自己的project 名称。这样，作者就可以使用速记符号为 \since命令的速记符号。

QDoc 在 Qt 6.9 中引入了这个配置变量。

另请参阅 \since.

项目

project 变量提供了与.qdocconf 文件相关的项目名称。这是所有项目都必须设置的变量。

项目名称用于为关联项目的索引文件命名。

project = QtCreator

这将导致创建一个名为qtcreator.index 的索引文件。

如果项目名称包含空格或特殊字符，则会在生成的索引文件名中用破折号（'-'）替换。

另请参阅依赖、索引和说明。

网址

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/ 。

另请参阅依赖、索引和url.示例。

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。

使用正文标题

在某些情况下，当图像在图形浏览器中呈现时，最好能为图像提供一个 "工具提示"。QDoc 提供了一种方法来做到这一点，在这种情况下，作为可选字符串向 \image命令中作为可选字符串给出的alt文本也被用作图片的标题属性。在 QDoc 配置文件中将 this 变量设置为usealttextastitle = true ，即可启用此行为。

QDoc 在 Qt 6.9 中引入了这个配置变量。

如何支持派生项目

该功能利用 QDoc 在创建 Qt 参考文档时生成的综合索引。

例如，qtgui.qdocconf（Qt GUI 的配置文件）包含以下变量定义：

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

...

项目变量名用于形成索引文件的文件名；在这种情况下，将创建qtgui.index 文件。url保存在索引文件中。之后，QDoc 在构建指向类、函数和索引中列出的其他内容的链接时，将以此为基础 URL。

另请参阅依赖、索引、项目和url。