QDoc 配置文件

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

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

一般说明

配置文件是"变量 = 值 "形式的条目列表。使用配置变量，您可以定义 QDoc 应在哪里找到各种源文件、图像和示例，以及生成的文档应放在哪里等。配置文件还可以包含include 等指令。有关示例，请参阅minimum.qdocconf。

您还可以使用配置变量让 QDoc 支持派生项目，即 QDoc 可以在您的项目文档中生成指向 Qt 在线文档中元素的链接。请参阅 "支持派生项目"部分。

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

可以使用"="或 "+="设置配置变量的值。不同的是，"="会覆盖之前的值，而 "+="会在当前值的基础上添加一个新值。

某些配置变量的值被解释为字符串列表，例如 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.io/
...
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.

配置变量

变量列表

• 定义
• 取决于
• 文件头（技术预览）
• 示例
• 示例
• 安装路径
• 文件扩展名
• 文件扩展名
• 警告丢失项目文件
• 排除文件
• 排除文件
• 额外图像
• 错误
• 文件头
• 文件头
• 文件扩展名
• HTML.footer
• HTML.postheader
• HTML.style
• 包含路径
• 忽略单词
• 忽略ince
• 图片
• 索引
• 语言
• 位置信息
• 宏
• 清单
• 模块头
• 导航
• 输出目录
• 输出格式
• 输出前缀
• 输出前缀
• 产品名称
• 项目
• 来源列表
• 资源
• 源文件扩展名
• 虚假
• 选项卡大小
• url
• url.examples
• 使用正文标题
• 版本
• 版本
• 警告限制

类别

• 通用配置变量
• 特定格式的配置变量

配置文件示例

• 最小配置文件：minimum.qdocconf
• Qt 配置文件：qtgui.qdocconf