创建 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

输入和输出目录

指定 source 目录的路径使 QDoc 能够找到 source 并生成文档。

 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 变量中指定的 header 和 source。

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

 outputdir  =    $SAMPLE_PROJECT/doc/html
 outputformats = HTML

QDoc 可以解析与 qdocconf 文件有关的路径及环境变量。

额外文件

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

 HTML.extraimages = extraImage.png \
                    extraImage2.png

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

Qt 帮助框架配置

QDoc 还将以 qhp 文件的形式导出 Qt 帮助项目 文件。然后，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 也会在每个HTML文件中嵌入 postheader、footer 和相关变量中的字符串。

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

QDoc 索引文件

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

另见：依赖 和 索引。

宏和其他配置

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

 macro.pi.HTML         = "Π"

这段代码将在 HTML 文件中用 Π 替换 \\pi。在浏览器中查看时将显示为希腊的 Π 符号。

另见：宏。

QML 添加

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

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

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

另见：outputprefixes，outputsuffixes。