QDoc 配置文件

在运行 QDoc 之前，您必须创建一个 QDoc 配置文件来告诉 QDoc 在哪里可以找到包含 QDoc 注释的源文件。配置文件的路径名在命令行中传递给 QDoc

/current/dir$ ../../bin/qdoc ./config.qdocconf

一般描述

配置文件是一系列以 "变量 = 值" 形式存在条目。通过使用配置变量，可以定义 QDoc 应该在哪里找到各种源文件、图像和示例，以及生成的文档应该放置在哪里。配置文件还可以包含如 include 之类的指令。例如，请参见 minimum.qdocconf。

您还可以使用配置变量让 QDoc 支持衍生项目，即 QDoc 可以在您项目的文档中生成本地 Docs 中的元素链接。有关支持衍生项目的更多信息，请参阅支持衍生项目部分。

有效的配置变量名可以包括大写和小写字母、数字和下划线 '_'。

配置变量的值可以使用 '=' 或 '+=' 来设置。区别在于 '=' 会覆盖之前的值，而 '+=' 会将新值添加到当前值。

某些配置变量的值被解释为字符串列表，例如：sourcedirs，而其他则被当作单个字符串处理。值字符串周围的引号是可选的，但包含它们可以在值字符串中包含特殊字符，例如

HTML.postheader = "<a href=\"index.html\">Home</a>"

如果条目跨越多行，则除了最后一行之外，每行的末尾都应使用反斜线

sourcedirs = kernel tools widgets

可以写成如下

sourcedirs = kernel \
             tools \
             widgets

如果值跨越多个行，但由于解释为一个字符串而合并，则行将以空格合并。

配置值的扩展

QDoc 支持配置文件中的环境变量扩展。例如，Qt 模块依赖于环境变量 QT_INSTALL_DOCS 来包含所有 Qt 模块文档项目的定义

include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)

要扩展的变量以 '$' 为前缀。为了在值字符串中使用字面量字符 '$'，请使用反斜线进行转义：‘\$’。

自 QDoc 6.0 版本以来，值也可以从其他配置变量中扩展。除了 $variable 语法之外，${variable} 语法也有效。后者消除了需要在变量名之间使用空白或非变量字符来分隔变量的需求。例如

baseurl = https://doc.qt.ac.cn/
...
url = ${baseurl}qtcreator

如果目标变量引用的是字符串列表，那么它们将在扩展值中使用空格合并

vars = foo \
       bar \
       baz

items = "Items: $vars"          # Expands to "Items: foo bar baz"

控制用于连接字符串列表的字符也是可能的

items = "Items: ${vars,|}"      # Expands to "Items: foo|bar|baz"
items = "Items: ${vars,,}"      # Expands to "Items: foo,bar,baz"
items = "Items: ${vars,}"       # Expands to "Items: foobarbaz"

由于扩展是在读取了所有变量之后执行的，因此它们的定义顺序不重要。

注意：不支持嵌套变量扩展。

扩展环境变量

当扩展环境变量时，${variable} 语法与 $variable 语法的行为不同。前者将变量的内容原地展开，作为配置文件的一部分进行解析，而后者只是将内容作为当前配置变量的值进行赋值。如果环境变量包含由空格分隔的元素列表，或者由 QDoc 识别的其它格式，这会有影响。

例如，如果环境变量 SRCDIRS 的值为 "../src/a ../src/b"，那么

sourcedirs  = $SRCDIRS      # Fail - value is interpreted as a single path.
sourcedirs  = ${SRCDIRS}    # Ok - whitespace is used as a delimiter.

QDoc 配置文件

一般描述

配置值的扩展

扩展环境变量

配置变量

变量列表

类别

配置文件示例