QDoc 配置文件

在运行 QDoc 之前，您必须创建一个 QDoc 配置文件，以告知 QDoc 如何查找包含 QDoc 注释的源文件。配置文件的路径需通过命令行传递给 QDoc：

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

概述

配置文件由一系列“变量 = 值”格式的条目组成。通过配置变量，您可以定义 QDoc 应从何处查找各种源文件、图像和示例，以及将生成的文档保存在何处等。配置文件还可以包含诸如include 之类的指令。示例请参见minimum.qdocconf。

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

有效的配置变量名称可以包含大写和小写字母、数字以及下划线“_”。

配置变量的值可使用 '=' 或 '+=' 进行设置。两者的区别在于：'=' 会覆盖之前的值，而 '+=' 会在当前值的基础上追加新值。

某些配置变量的值会被解释为字符串列表，例如： sourcedirs，而其他则被视为单个字符串。值字符串周围的双引号是可选的，但使用双引号可允许在值字符串中使用 '=' 和 ' " ' 等特殊字符，例如：

HTML.postheader = "<ul class=\"breadcrumbs\">"

如果某项内容跨多行，请在除最后一行以外的每行末尾使用反斜杠：

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.

配置变量

变量列表

• 定义
• depends
• 文档在头文件中
• 示例目录
• 示例
• 示例安装路径
• 示例文件扩展名
• 示例.关于缺失图片的警告
• 示例.提示缺少项目文件
• 被排除的目录
• excludefiles
• 额外图片
• 虚假信息
• 头文件目录
• headers
• headers.fileextensions
• HTML.footer
• HTML.postheader
• HTML.postpostheader
• HTML.style
• 包含路径
• includeprivate
• 忽略词
• 忽略起始时间
• imagedirs
• imagesoutputdir
• 索引
• language
• locationinfo
• logwarnings
• 宏
• 清单元数据
• 模块头
• navigation
• 输出目录
• 输出格式
• 输出前缀
• 输出后缀
• parsecpp注释
• preliminary
• productname
• project
• 项目根目录
• 显示自动生成的文档
• 源目录
• 源文件
• 源文件扩展名
• 多余的
• 制表符宽度
• url
• url.示例
• url.sources
• 将替代文本用作标题
• 版本
• 版本符号
• 警告限制

分类

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

配置文件示例

• 一个最基本的配置文件：minimum.qdocconf
• Qt 配置文件：qtgui.qdocconf