创建 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 还会导出一个Qt Help 项目文件，并生成一个qhp 文件。随后，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.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。 然后，其他项目可以定义对该索引文件的依赖关系，以便链接到该项目中的文档。

另请参阅：depends和indexes。

宏和其他配置

存在用于替换 HTML 字符的宏，它们有助于生成符合 HTML 规范的特定字符。

macro.pi.HTML         = "Π"

该代码片段将在 HTML 文件中将所有\\pi 替换为&Pi ；在浏览器中查看时，该字符将显示为希腊字母 Π。

另请参阅： 宏。

QML 新增内容

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

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

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

另请参阅：outputprefixes、outputsuffixes。