通用配置变量

使用一般的QDoc配置变量，您可以定义QDoc将在哪里找到生成文档所需的各个源文件，以及存放生成的文档的目录。您还可以对QDoc本身进行一些轻微的操纵，控制其输出和处理行为。

codeindent

codeindent变量指定QDoc在写入代码片段时使用的缩进级别。

QDoc最初使用硬编码的四个空格作为代码缩进值，以确保代码片段可以很容易地从周围文本中区分出来。由于我们可以使用样式表来调整某些类型HTML元素的显示，因此这种缩进级别不一定总是必需的。

codeprefix, codesuffix

codeprefix和codesuffix变量指定一对字符串，每个代码片段都被这对字符串包围。

defines

defines变量指定QDoc将识别并响应的C++预处理器符号。

当使用defines变量指定预处理器符号时，您还可以使用\if命令来包含只有在预处理器符号定义的情况下才会包含的文档。

defines = QT_GUI_LIB

这确保QDoc将处理需要定义这些符号的代码。例如

#ifdef Q_GUI_LIB
void keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay = -1)
#endif

您也可以使用命令行上的-D选项手动在命令行上定义预处理器符号。例如

currentdirectory$ qdoc -Dqtforpython qtgui.qdocconf

在这种情况下，-D选项确保当QDoc处理在qtgui.qdocconf文件中定义的源文件时，定义了qtforpython预处理器符号。

另请参阅falsehoods和\if。

depends

depends变量定义了其他文档项目列表，该项目依赖于解决类型继承的链接目标以及文档需要链接的所有其他内容。

与Qt本身一样，Qt的文档分布在不同模块中。在多模块文档项目中，单个模块的最小依赖集合是实际的构建依赖。此外，如果一个文档项目（模块）是整个文档集的顶级入口点并提供导航链接，则每个模块的文档都应该将其作为依赖项包含在内。

当QDoc为项目生成文档时，它还会生成一个包含项目中每个可链接实体URL的.index文件。每个依赖项都是一个（小写）项目名称。此名称必须与为该项目生成的索引文件的基名称匹配。

depends = \
    qtdoc \
    qtcore \
    qtquick

当在具有依赖关系并使用depends变量的项目上调用QDoc时，必须通过命令行选项传递一个或多个-indexdir路径。QDoc使用这些路径来搜索依赖项的索引文件。

qdoc mydoc.qdocconf -outputdir $PWD/html -indexdir $QT_INSTALL_DOCS

根据以上，QDoc将搜索一个名为$QT_INSTALL_DOCS/qtdoc/qtdoc.index的文件，以查找对qtdoc的依赖项。如果在依赖项中找不到索引文件，QDoc将输出警告。

depends命令还接受一个特殊值'*'。这指示QDoc加载在指定的索引目录中找到的所有索引文件；即“依赖于所有内容”。

depends = *

另请参阅indexes、project和url。

exampledirs

exampledirs变量指定包含示例文件源代码的目录。

变量examples和exampledirs被\quotefromfile、\quotefile和\example命令使用。如果同时定义了变量examples和exampledirs，则QDoc将在两者中搜索，首先在examples中，然后在实际的exampledirs中。

QDoc将按照指定的顺序搜索目录，并接受它找到的第一个匹配文件。它只搜索指定的目录，不会搜索子目录。

exampledirs = $QTDIR/doc/src \
              $QTDIR/examples \
              $QTDIR \
              $QTDIR/qmake/examples

examples    = $QTDIR/examples/widgets/analogclock/analogclock.cpp

当处理

\quotefromfile widgets/calculator/calculator.cpp

QDoc将检查是否有一个被称为calculator.cpp的文件在examples变量中的值中列出。如果没有，则在exampledirs变量中进行搜索，并首先查看是否存在一个名为

$QTDIR/doc/src/widgets/calculator/calculator.cpp

如果它不存在，QDoc将继续寻找一个名为

$QTDIR/examples/widgets/calculator/calculator.cpp

以此类推。

另请参阅examples。

examples

examples变量允许您指定除由exampledirs变量指定的目录中的文件之外的单独示例文件。

examples和exampledirs变量被\quotefromfile、\quotefile和\example命令使用。如果同时定义了examples和exampledirs变量，则QDoc将在两者中搜索，并首先在examples中，然后在实际的exampledirs中。

QDoc将按照指定的顺序搜索examples变量列出的值，并接受它找到的第一个值。

请参见exampledirs命令的详细示例。但请注意，如果您知道文件已在examples变量中列出，则无需指定其路径。

\quotefromfile calculator.cpp

也请参见exampledirs。

examplesinstallpath

examplesinstallpath变量设置本项目管理示例的根路径，位于安装示例目录下的安装示例目录。

假设所有示例的根安装路径为QT_INSTALL_EXAMPLES，那么路径

<QT_INSTALL_EXAMPLES>/<examplesinstallpath>/<example_path>

将用于引用本文档项目中单个示例的路径。这些路径记录在示例清单文件中，由Qt Creator读取。

为确保路径正确，examplesinstallpath必须与exampledirs中列出的目录之一匹配。每个\example命令的参数路径相对于exampledirs路径。

例如

exampledirs = ./snippets \
              ../../../examples/mymodule

examplesinstallpath = mymodule

并且给定以下\example命令

/*!
    \example basic/hello
    ...
*/

那么，路径mymodule/basic/hello将记录在本示例的清单文件中。

也请参见：exampledirs，\example，以及\meta。

examples.fileextensions

examples.fileextensions变量指定QDoc在收集显示在文档中示例文件时要查找的文件扩展名。

默认扩展名有*.cpp、*.h、*.js、*.xq、*.svg、*.xml和*.ui。

扩展名以标准通配符表达式给出。您可以使用'+'添加文件扩展名到过滤器中。例如

examples.fileextensions += *.qrc

也请参见headers.fileextensions。

excludedirs

excludedirs变量用于列出不应处理（即使由sourcedirs或headerdirs变量包含）的目录。

例如

sourcedirs =  src/corelib
excludedirs = src/corelib/tmp

执行时，QDoc将排除列出的目录以供进一步考虑。这些目录中的文件不会被QDoc读取。

也请参见excludefiles。

excludefiles

excludefiles变量允许您指定不应由QDoc处理的单个文件。

excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
                $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp

如果将上述内容包含在qtbase的qdocconf文件中，则不会为QWidget生成类文档。

从Qt 5.6开始，excludefiles也识别简单的通配符（'*'和'?'）。例如，要排除所有私有Qt头文件被解析，定义以下

excludefiles += "*_p.h"

也请参见excludedirs。

extraimages

extraimages变量告诉QDoc要将特定图像合并到生成的文档中。

QDoc会自动将图文件从imagedirs路径拷贝到输出目录中，如果图中使用了\image或\inlineimage命令。如果您要额外复制图像，您必须使用extraimages变量来指定它们。

一般语法为format.extraimages = image。

关于上下文实例，请参考HTML.postheader变量的描述。

示例

HTML.extraimages = images/qt-logo.png

另请参阅图像和imagedirs。

falsehoods

falsehoods变量定义了指定预处理器符号的布尔值。

该变量的值是正则表达式（有关详细信息，请参阅QRegularExpression）。如果未设置预处理器符号的此变量，QDoc假定其布尔值为true。例外情况是'value=0'，它始终为false。

QDoc将识别并能够评估以下预处理器语法

#ifdef NOTYET
 ...
#endif

#if defined (NOTYET)
 ...
#end if

然而，面对类似以下未知的语法

#if NOTYET
    ...
#endif

QDoc将默认评估它为true，除非在falsehoods变量条目中指定了预处理器符号

falsehoods = NOTYET

另请参阅defines。

generateindex

generateindex变量包含一个布尔值，指定在生成HTML文档时是否生成索引文件。

默认情况下，总是与HTML文档一起生成索引文件，因此此变量通常仅在禁用此功能（将值设置为false）或启用WebXML输出的索引生成时（将值设置为true）使用。

headerdirs

headerdirs变量指定包含与文档中使用的源文件关联的头文件的目录。

headerdirs = $QTDIR/src \
             $QTDIR/extensions/activeqt \
             $QTDIR/extensions/motif \
             $QTDIR/tools/designer/src/lib/extension \
             $QTDIR/tools/designer/src/lib/sdk \
             $QTDIR/tools/designer/src/lib/uilib

当执行时，QDoc将首先通过在headers变量中指定的头文件进行操作，然后在headerdir变量中指定的目录中查找（包括所有子目录），构建类及其功能的内部结构。

然后它将读取sources变量中指定的源代码，以及在sourcedirs变量中指定的目录中的源代码（包括所有子目录），将文档与从头文件检索的结构合并。

如果同时定义了headers和headerdirs变量，QDoc将按顺序读取两者，首先headers然后headerdirs。

在指定的目录中，QDoc仅读取headers.fileextensions变量中指定的具有fileextensions的文件。指定给headers的文件将读取，而不考虑它们的文件扩展名。

另请参阅headers和headers.fileextensions。

头文件

headers 变量允许您指定单个头文件，除了由 headerdirs 变量指定的目录中的头文件。

headers = $QTDIR/src/gui/widgets/qlineedit.h \
          $QTDIR/src/gui/widgets/qpushbutton.h

处理 headers 变量时，QDoc 的行为与处理 headerdirs 变量时的行为相同。更多信息，请参阅 headerdirs 变量。

另请参阅 headerdirs。

headers.fileextensions

headers.fileextensions 变量指定头文件使用的扩展名。

当处理 headerdirs 变量中指定的头文件时，QDoc 将仅读取 headers.fileextensions 变量中指定的文件扩展名对应的文件。因此，QDoc 可以避免读取无关文件而浪费时间。

默认扩展名是 *.ch, *.h, *.h++, *.hh, *.hpp, 和 *.hxx。

扩展名以标准通配符表达式给出。您可以使用'+'添加文件扩展名到过滤器中。例如

header.fileextensions += *.H

另请参阅 headerdirs。

includepaths

includepaths 变量用于将额外的包含路径传递给 QDoc 用于解析文档注释的 C++ 代码的 Clang 解析器。

该变量接受以 -I（包含路径）、-F（macOS 框架包含路径）或 -isystem（系统包含路径）为前缀的路径列表。如果省略前缀，则默认使用 -I。

相对于当前 .qdocconf 文件的路径将被解析为绝对路径。不存在的文件系统路径将被忽略。

另请参阅 moduleheader。

ignorewords

ignorewords 变量用于指定 QDoc 解析超链接目标时将被忽略的字符串列表。

QDoc 具有自动链接功能，对类似于 C++ 或 QML 实体的单词进行尝试链接。具体来说，如果字符串至少有 三个字符长，没有空格，并且

• 是一个 camelCase 单词，即它包含索引大于零的至少一个大写字母，或者
• 包含子串 () 或 ::，或者
• 包含至少一个特殊字符，@ 或 _。

将一个规范单词添加到 ignorewords 中可以阻止 QDoc 自动将该单词链接。例如，如果单词 OpenGL 是一个有效的链接目标（节、\page 或 \externalpage 标题），则可以使用以下方法避免每个出现的超链接：

ignorewords += OpenGL

使用 \l 显式链接仍然适用于忽略的单词。

ignorewords 变量自 QDoc 5.14 版本引入。

ignoresince

ignoresince 变量用于为传递给 \since 命令的版本设置一个截止值。所有低于截止值的 \since 命令都被忽略，且不生成输出。

截止值是项目特有的。项目名称可以作为子变量定义。默认项目名称是 Qt。例如

ignoresince      = 5.0
ignoresince.QDoc = 5.0

以下将忽略其中版本为4或更低的 \since 命令，如果项目是 QDoc 或未定义。

\since 3.2          # Ignored
\since 5.2          # Documented (as 'Qt 5.2')
\since QDoc 4.6     # Ignored
\since QtQuick 2.5  # Documented

ignoresince 变量是在 QDoc 5.15 中引入的。

另请参阅 \since 命令。

imagedirs

imagedirs 变量指定包含文档中使用图像的目录。

images 和 imagedirs 变量由 \image 和 \inlineimage 命令使用。如果两个变量中的任意一个都定义了，QDoc 将在两者中搜索。首先在 images 中搜索，然后在 imagedirs 中搜索。

QDoc将按照指定的顺序搜索目录，并接受它找到的第一个匹配文件。它只搜索指定的目录，不会搜索子目录。

imagedirs = $QTDIR/doc/src/images \
            $QTDIR/examples

images    = $QTDIR/doc/src/images/calculator-example.png

当处理

\image calculator-example.png

然后 QDoc 将检查是否存在一个名为 calculator-example.png 的文件，它在 images 变量的值中列出。如果没有，它将在 imagedirs 变量中搜索

$QTDIR/doc/src/images/calculator-example.png

如果文件不存在，QDoc 将寻找文件名

$QTDIR/examples/calculator-example.png

language

language 变量指定在文档中使用的源代码语言。具体来说，它定义了在 \code .. \endcode 块内解析源代码的默认语言。

language = Cpp

默认语言是 C++ (Cpp)，无需显式指定。如果文档中的代码片段主要包含 QML 代码，将 QML 设置为默认

language = QML

另请参阅 code-command。

locationinfo

locationinfo 布尔变量决定是否将每个实体的详细位置信息写入 .index 文件和 .webxml 文件（当使用 WebXML 输出格式时）。

位置信息由源代码中声明或文档注释块的完整路径和行号组成。

将此设置为 false 将关闭位置信息

locationinfo = false

默认值是 true。

locationinfo 变量是在 QDoc 5.15 中引入的。

macro

macro 变量用于创建您自己的简单 QDoc 命令。语法是 macro.command = definition，其中定义是用 QDoc 语法编写的。

可以为输出生成的特定类型限制宏变量的使用。例如，通过在宏名称后附加 .HTML，该宏只会在生成 HTML 输出时使用。

macro.key              = "\\b"
macro.raisedaster.HTML = "<sup>*</sup>"

第一个宏定义了 \key 命令，使用粗体字渲染其参数。第二个宏定义了 \raisedaster 命令，用于渲染上标星号，但仅当生成 HTML 时。

宏也可以接收最多七个参数

macro.hello            = "Hello \1!"

参数的传递方式与其他命令相同

\hello World

当使用多个参数或当参数包含空格时，将每个参数用花括号括起来

macro.verinfo          = "\1 (version \2)"

\verinfo {QFooBar} {1.0 beta}

对于扩展宏，可以添加特定宏选项 match 进行额外的正则表达式模式匹配。

例如，

macro.qtminorversion       = "$QT_VER"
macro.qtminorversion.match = "\\d+\\.(\\d+)"

这创建了一个宏 \qtminorversion，该宏扩展到基于 QT_VER 环境变量的次要版本。

一个定义匹配模式的宏会输出所有捕获组（括号内的内容）连接在一起的字符串，或者如果不包含任何捕获组，则输出精确匹配的字符串。

有关预定义宏的更多信息，请参阅宏。

manifestmeta

manifestmeta变量指定了由QDoc生成的示例清单文件中包含的附加元内容。

有关更多信息，请参阅清单元内容部分。

moduleheader

moduleheader变量定义了文档化的C++模块的模块头名称。

文档C++ API的项目需要模块级的头文件，该文件包含模块的所有公共类、命名空间和头文件。QDoc中的Clang解析器使用此文件为模块构建预编译头（PCH），以提高解析源文件的速度。

默认情况下，使用项目名称作为模块头名称。

project = QtCore

使用上述项目名称，QDoc将在所有已知包含路径中搜索模块头QtCore；首先使用作为命令行参数传递的路径，然后使用includepaths变量中列出的路径。

如果找不到模块头，QDoc将发出警告。然后它将尝试根据headerdirs变量中列出的头文件构建一个人工模块头。

对于Qt文档项目，如果设置了project变量，则构建系统通常提供QDoc正确的包含路径以定位模块头，moduleheader变量为QDoc提供一个备选文件名以进行搜索。

如果项目不包含C++文档，应指令QDoc跳过生成PCH，将moduleheader设置为空字符串。

# No C++ code to document in this project
moduleheader =

另请参阅includepaths和project。

naturallanguage

naturallanguage变量指定了QDoc生成的文档所使用的自然语言。

naturallanguage = zh-Hans

为了与旧版文档的兼容性，默认语言为en。

QDoc会将自然语言信息添加到它生成的HTML中，使用lang和xml:lang属性。

另请参阅sourceencoding、outputencoding、C.7. lang和xml:lang属性和最佳实践13：使用Hans和Hant代码。

navigation

如果定义，则navigation子变量将设置每个页面的导航栏中可见的首页、落地页、C++类页面和QML类型页面。

在一个具有多个子项目（例如，Qt模块）的项目中，每个子项目通常定义其自己的落地页，而所有子项目使用相同的首页。

子变量

例如

# Common configuration
navigation.homepage  = index.html
navigation.hometitle = "Qt $QT_VER"

# qtquick.qdocconf
navigation.landingpage    = "Qt Quick"
navigation.cppclassespage = "Qt Quick C++ Classes"
navigation.qmltypespage   = "Qt Quick QML Types"

以上配置将为Item QML类型生成以下导航栏

Qt 5.10 > Qt Quick > QML Types > Item QML Type

outputdir

outputdir变量指定了QDoc将生成文档的目录。

outputdir = $QTDIR/doc/html

在$QTDIR/doc/html中定位生成的Qt参考文档。例如，QWidget类的文档位于

$QTDIR/doc/html/qwidget.html

关联的图像将放入images子目录中。

outputencoding

outputencoding变量指定了QDoc生成的文档所使用的编码。

outputencoding = UTF-8

默认情况下，输出编码为ISO-8859-1（Latin1），以兼容旧文档。当生成某些语言（尤其是非欧洲语言）的文档时，这并不足够，需要使用如UTF-8之类的编码。

QDoc将使用此编码对HTML进行编码，并生成正确的声明来指示浏览器使用哪种编码。应指定naturallanguage配置变量，以便为浏览器提供完整的字符编码和语言信息集。

另请参阅outputencoding和naturallanguage。

outputformats

outputformats变量指定了生成文档的格式。

自Qt 5.11以来，QDoc支持HTML和WebXML格式；自Qt 5.15以来，它还可以生成DocBook格式的文档。如果没有指定outputformats，QDoc将以HTML（默认格式）生成文档。所有输出格式都可以指定，包括专用输出目录和其他设置。例如

outputformats = WebXML HTML
WebXML.nosubdirs = true
WebXML.outputsubdir = webxml
WebXML.quotinginformation = true

这将在默认设置下生成HTML文档，同时将WebXML文档生成到输出子目录webxml中。

outputprefixes

outputprefixes变量指定了文件类型和要附加到生成文档中输出文件名的前缀之间的映射。

QDoc支持为QML类型、C++类、命名空间和头文件参考页面的文件名添加输出前缀。

outputprefixes     = QML CPP
outputprefixes.QML = uicomponents-
outputprefixes.CPP = components-

默认情况下，包含QML类型API文档的文件以qml-为前缀。在上面的示例中，使用的是前缀uicomponents-。

同样，上面的示例中C++类型的文档页面以components-为前缀。默认情况下，C++类型页面没有前缀。

outputsuffixes

outputsuffixes变量指定了文件类型和输出文件名中模块或类型名称的附加后缀之间的映射。

QDoc支持向模块页面、QML类型、C++类、命名空间和头文件参考页面的文件名添加输出后缀。

默认情况下不使用后缀。如果定义了QML输出后缀，它将作为后缀应用于文件名中的模块名称，这些名称用于QML类型和QML模块页面。

C++类型的文件名不包含模块名。如果定义了CPP输出后缀，它将作为后缀应用于类型名称。

outputsuffixes = QML CPP
{outputsuffixes.QML,outputsuffixes.CPP} = -tp

有了上面的定义，假设有一个QML模块名FooBar和默认的输出前缀（qml-），生成的QML类型FooWidget的文件名为qml-foobar-tp-foowidget.html。

同样，对于C++类QFoobar，QDoc生成qfoobar-tp.html。

outputsuffixes变量是在QDoc 5.6中引入的。

qhp

子变量qhp用于定义要写入Qt帮助项目（qhp）文件的信息。

有关此过程的信息，请参阅创建帮助项目文件章节。

从QDoc 6.6开始，将基本qhp变量设置为true意味着期望有效的帮助项目配置。

qhp = true

然后，如果没有项目配置定义了qhp.projects，QDoc会发出警告。这可以用来确保所有具有共享顶级.qdocconf文件（例如Qt）的文档项目都进行了正确配置。

要关闭警告，请将变量设置为false。

sourcedirs

sourcedirs变量指定包含用于文档的.cpp或.qdoc文件的目录。

sourcedirs  += .. \
               ../../../examples/gui/doc/src

当执行时，QDoc首先会读取在header变量中指定的头文件，以及在headerdir变量指定的目录（包括所有子目录）中找到的头文件，构建类及其函数的内部结构。

然后它会读取在sources中指定的源文件和位于sourcedirs变量指定的目录中（包括所有子目录）的源文件，将文档与从头文件检索到的结构合并。

如果定义了sources和sourcedirs变量，QDoc将读取这两个变量，首先是sources然后是sourcedirs。

在指定的目录中，QDoc只会读取在sources.fileextensions变量中指定的文件格式的文件。由sources指定的文件将独立于其文件格式进行读取。

参见 sources和 sources.fileextensions.

sourceencoding

sourceencoding变量指定源代码和文档使用的编码。

sourceencoding = UTF-8

默认情况下，源编码为ISO-8859-1（拉丁1），以便与旧版文档兼容。对于某些语言，特别是非欧洲语言，这不足以满足需求，需要使用UTF-8等编码。

虽然QDoc将使用该编码读取源代码和文档文件，但C++编译器的限制可能防止您在源代码注释中使用非ASCII字符。在这种情况下，可以将API文档完全写入文档文件中。

参见naturallanguage和outputencoding。

sources

sources变量允许您指定除了通过sourcedirs变量指定的目录之外的单个源文件。

sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
          $QTDIR/src/gui/widgets/qpushbutton.cpp

在处理sources变量时，QDoc的行为与处理sourcedirs变量时的行为相同。有关更多信息，请参阅sourcedirs变量。

参见sourcedirs。

sources.fileextensions

sources.fileextensions变量筛选源目录内的文件。

当处理sourcedirs变量指定的源文件时，QDoc只会读取在sources.fileextensions变量中指定的文件扩展名。这样，QDoc就可以避免浪费时间去读取无关的文件。

默认扩展名有*.c++, *.cc, *.cpp, *.cxx, *.mm, *.qml和*.qdoc。

扩展名以标准通配符表达式给出。您可以使用'+'添加文件扩展名到过滤器中。例如

sources.fileextensions += *.CC

参见sourcedirs和(sources-variable} {sources}。

spurious

spurious变量排除了指定的QDoc警告，这些警告使用标准的通配符表达式指定。

spurious = "Cannot find .*" \
"Missing .*"

确保匹配以下任一表达式的警告在运行QDoc时不会被包含在输出中。例如以下警告将被省略：

src/opengl/qgl_mac.cpp:156: Missing parameter name

syntaxhighlighting

syntaxhighlighting变量指定QDoc是否应在它生成的文档中为其引用的源代码执行语法高亮。

syntaxhighlighting = true

将启用对所有支持编程语言的语法高亮。

tabsize

tabsize变量定义了制表符字符的大小。

tabsize = 4

将制表符字符的大小设为4个空格。该变量的默认值是8，不需要指定。

tagfile

tagfile变量指定当生成HTML时写入的Doxygen标记文件。

version

version变量指定文档化软件的版本号。

version = 5.6.0

当指定版本号时（使用或变量在.qdocconf文件中），它可以通过相应的\version命令用于文档。

另请参阅 versionsym。

versionsym

versionsym 变量指定了一个 C++ 预处理器符号，它定义了记录软件的版本号。

versionsym = QT_VERSION_STR

QT_VERSION_STR 在 qglobal.h 中如下定义：

#define QT_VERSION_STR   "5.14.1"

当指定版本号时（使用或变量在.qdocconf文件中），它可以通过相应的\version命令用于文档。

另请参阅 \version。

warninglimit

warninglimit 变量设置了允许的最大文档警告数量。如果超出此限制，QDoc 将继续正常工作，但退出时使用警告计数作为错误代码。如果未超出此限制或未定义 warninglimit，QDoc 进程将使用 0 退出，假设没有其他关键错误。

将 warninglimit 设置为 0 表示任何警告都表示失败。

例如，

# Fail the documentation build if we have more than 100 warnings
warninglimit = 100
warninglimit.enabled = true

warninglimit 变量是在 Qt 5.11 中引入的。