创建 QDoc 配置文件

为生成文档，QDoc 使用扩展名为qdocconf 的配置文件来存储配置设置。

QDoc 配置文件》一文更详细地介绍了各种配置变量。

QDoc 配置文件

QDoc 的配置设置可以存在于单个qdocconf文件中，但也可以存在于其他 qdocconf 文件中。include(<filepath>) 命令允许配置文件包含其他配置文件。

QDoc 有两种输出：HTML 文档和 DocBook XML 格式的文档。这两种输出的主要区别在于，HTML 文档需要在配置文件中包含 HTML 样式信息。DocBook 文档则不需要，稍后可以通过一个单独的进程来为 DocBook 文档设计样式。因此，DocBook 允许对相同的信息使用不同的样式，因而更加灵活。

要运行 QDoc，需要将项目配置文件作为参数提供。

qdoc project.qdocconf

项目配置包含 QDoc 用于创建文档的信息。

项目信息

QDoc 使用project 信息来生成文档。

project = QDoc Project
description = Sample QDoc project

输入和输出目录

指定源目录的路径可让 QDoc 查找源并生成文档。

sourcedirs = <path to source code>
exampledirs = <path to examples directory>
imagedirs = <path to image directory>

sources.fileextensions = "*.cpp *.qdoc *.mm *.qml"
headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx"
examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml"
examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng"

QDoc 将处理fileextensions 变量中指定的头文件和源文件。

同样，QDoc 也需要输出目录的路径。outputformats 变量决定文档类型。这些变量应放在不同的配置文件中，以便模块化构建文档。

outputdir  =    $SAMPLE_PROJECT/doc/html
outputformats = HTML

QDoc 可以解析相对于 qdocconf 文件的路径以及环境变量。

额外文件

QDoc 会将生成的文档输出到输出目录中指定的目录。还可以指定 QDoc 应输出的额外文件。

HTML.extraimages = extraImage.png \
                   extraImage2.png

extraImage.png 和extraImage2.png 文件将被复制到 HTML 输出目录。

Qt Help 框架配置

QDoc 还将在qhp 文件中导出Qt Help 项目文件。然后，qhelpgenerator 会使用 qhp 文件将文档打包到qch 文件中。Qt Creator 和Qt Assistant 会读取 qch 文件以显示文档。

创建帮助项目文件》一文介绍了配置选项。

HTML 配置

QDoc 有一个 HTML 生成器，可使用各种配置设置将文档集导出为 HTML 文件。QDoc 会将生成的文档放到outputdir 变量指定的目录中。

outputformats = HTML
outputdir =  <path to output directory>

QDoc 需要知道生成 HTML 的样式和模板的位置。通常，模板目录包含scripts 、images 和style 目录，其中包含脚本和 CSS 文件。

主要配置变量有

HTML.postheader
HTML.postpostheader
HTML.postheader
HTML.footer

HTML.headerstyles
HTML.stylesheets = template/style/style.css \
                   template/style/style1.css

HTML.scripts = template/scripts/script.js

HTML.headerstyles 变量将样式信息插入 HTML 文件，而HTML.stylesheets 则指定 QDoc 应将哪些文件复制到输出目录。此外，QDoc 还会将postheader 、footer 和相关变量中的字符串嵌入到每个 HTML 文件中。

特定于格式的配置变量文章概述了每个变量的用法。

QDoc 索引文件

文档项目可以通过指定一组依赖项或一组指向该项目所依赖的索引文件的直接路径，链接到其他项目中的目标。当 QDoc 为一个项目生成文档时，它还会生成一个.index 文件，其中包含指向项目中每个可链接实体的 URL。其他项目可以定义对索引文件的依赖关系，以便链接到该项目中的文档。

另请参见：依赖和索引。

宏和其他配置

存在用于替换 HTML 字符的宏，有助于生成特定的 HTML 有效字符。

macro.pi.HTML         = "Π"

代码片段将在 HTML 文件中用&Pi; 替换\\pi ，在浏览器中显示为希腊文 Π 符号。

另请参见： 宏。

QML 新增功能

QDoc 能够为 QDoc 注释解析 QML 文件。如果扩展类型包含在fileextensions变量中，QDoc 将解析带有 QML 扩展名.qml 的文件。

此外，生成的 HTML 文件还可以在 QDoc 配置文件中指定的 QML 模块名称后加上前缀和后缀。

outputprefixes = QML
outputprefixes.QML = uicomponents-
outputsuffixes = QML
outputsuffixes.QML = -tp

另请参阅：输出前缀（outputprefixes）、输出后缀（outputsuffixes）。