创建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帮助框架配置

QDoc还将导出一个Qt帮助项目文件，以qhp文件格式。该qhp文件随后由qhelpgenerator用于将文档打包成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 为项目生成文档时，它还将生成一个包含指向项目中每个可链接实体的 URL 的 .index 文件。其他项目可以定义对索引文件的依赖关系，以便链接到该项目中包含的文档。

另见：depends 和 indexes。

宏和其他配置

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

macro.pi.HTML         = "Π"

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

另见： macro。

QML 扩展

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

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

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

另见： outputprefixes，outputsuffixes。