With the general QDoc configuration variables, you can define where QDoc will find the various source files it needs to generate the documentation, as well as the directory to put the generated documentation. You can also do some minor manipulation of QDoc itself, controlling its output and processing behavior.
The
alias
variable renames a QDoc command.
The general syntax is
alias.original-command-name = temporary-command-name
.
alias.e = i
This renames the built-in command \e (italics) to be \i. The
alias
variable is often used for compatibility reasons.
另请参阅 macro .
The
codeindent
variable specifies the level of indentation that QDoc uses when writing code snippets.
QDoc originally used a hard-coded value of four spaces for code indentation to ensure that code snippets could be easily distinguished from surrounding text. Since we can use stylesheets to adjust the appearance of certain types of HTML elements, this level of indentation is not always required.
The
codeprefix
and
codesuffix
variables specify a pair of strings that each code snippet is enclosed in.
The
定义
variable specifies the C++ preprocessor symbols that QDoc will recognize and respond to.
When a preprocessor symbol is specified using the
定义
variable, you can also use the
\if
command to enclose documentation that only will be included if the preprocessor symbol is defined.
The values of the variable are regular expressions (see QRegExp for details). By default, no symbol is defined, meaning that code protected with #ifdef...#endif will be ignored.
defines = Q_QDOC \
QT_.*_SUPPORT \
QT_.*_LIB \
QT_COMPAT \
QT3_SUPPORT \
Q_OS_.* \
Q_BYTE_ORDER \
__cplusplus
This ensures that QDoc will process the code that requires these symbols to be defined. For example:
#ifdef Q_OS_WIN HDC getDC() const; void releaseDC(HDC) const; #endif
Since the Q_OS_.* regular expression (specified using the
定义
variable) matches
Q_OS_WIN
, QDoc will process the code within #ifdef and #endif in our example.
You can also define preprocessor symbols manually on the command line using the -D option. For example:
currentdirectory$ qdoc -Dqtforpython qtgui.qdocconf
In this case the -D option ensures that the
qtforpython
preprocessor symbol is defined when QDoc processes the source files defined in the qtgui.qdocconf file.
另请参阅 falsehoods and \if .
The
depends
variable defines a list of other documentation projects that this project depends on for resolving link targets for type inheritance and anything else the documentation needs to link to.
Like Qt itself, documentation for Qt is distributed across multiple modules. In a multi-module documentation project, the minimum set of dependencies for a single module consists of actual build dependencies. In addition, if there is a documentation project (module) that acts as a top-level entry point for the entire documentation set and provides navigation-variable [navigation} links, each module documentation should include it as a dependency.
When QDoc generates documentation for a project, it will also generate an
.index
file containing URLs to each linkable entity in the project. Each dependency is a (lowercase) name of a project. This name must match with the base name of the index file generated for that project.
depends = \
qtdoc \
qtcore \
qtquick
When invoking QDoc on a project that has dependencies and uses the
depends
variable, one or more
-indexdir
path(s) must be passed as command line option(s). QDoc uses these paths to search for the dependencies' index files.
qdoc mydoc.qdocconf -outputdir $PWD/html -indexdir $QT_INSTALL_DOCS
With above, QDoc will search for a file
$T_INSTALL_DOCS/qtdoc/qtdoc.index
for a dependency to
qtdoc
. If an index file for a dependency is not found, QDoc will output a warning.
The
depends
command accepts also a special value of '*'. This instructs QDoc to load all index files found in specified index directories; that is, "depends on everything".
depends = *
另请参阅 indexes , project ，和 url .
The
exampledirs
variable specifies the directories containing the source code of the example files.
The examples and exampledirs variables are used by the \quotefromfile , \quotefile and \example commands. If both the examples and exampledirs variables are defined, QDoc will search in both, first in examples then in exampledirs .
QDoc will search through the directories in the specified order, and accept the first matching file it finds. It will only search in the specified directories, not in subdirectories.
exampledirs = $QTDIR/doc/src \
$QTDIR/examples \
$QTDIR \
$QTDIR/qmake/examples
examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp
When processing
\quotefromfile widgets/calculator/calculator.cpp
QDoc will see if there is a file called
calculator.cpp
listed as a value in the
examples
variable. If there isn't, it will search in the
exampledirs
variable, and first see if there exists a file called
$QTDIR/doc/src/widgets/calculator/calculator.cpp
If it doesn't, QDoc will continue looking for a file called
$QTDIR/examples/widgets/calculator/calculator.cpp
and so forth.
另请参阅 examples .
The
examples
variable allows you to specify individual example files in addition to those located in the directories specified by the
exampledirs
变量。
The
examples
and
exampledirs
variables are used by the
\quotefromfile
,
\quotefile
and
\example
commands. If both the
examples
and
exampledirs
variables are defined, QDoc will search in both, first in
examples
then in
exampledirs
.
QDoc will search through the values listed for the
examples
variable, in the specified order, and accept the first one it finds.
For an extensive example, see the
exampledirs
command. But note that if you know the file is listed in the
examples
variable, you don't need to specify its path:
\quotefromfile calculator.cpp
另请参阅 exampledirs .
The
examples.fileextensions
variable specifies the file extensions that QDoc will look for when collecting example files for display in the documentation.
The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml and *.ui.
The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example:
examples.fileextensions += *.qrc
另请参阅 headers.fileextensions .
The
excludedirs
variable is for listing directories that should
not
be processed by QDoc, even if the same directories are included by the
sourcedirs
or
headerdirs
变量。
例如：
sourcedirs = src/corelib excludedirs = src/corelib/tmp
When executed, QDoc will exclude the listed directories from further consideration. Files in these directories will not be read by QDoc.
另请参阅 excludefiles .
The
excludefiles
variable allows you to specify individual files that should
not
be processed by QDoc.
excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
$QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp
If you include the above in your qdocconf file for qtbase, there will be no class documentation generated for QWidget .
Since Qt 5.6, also simple wildcards ('*' and '?') are recognized by
excludefiles
. For example, to exclude all private Qt header files from being parsed, define the following:
excludefiles += "*_p.h"
另请参阅 excludedirs .
The
extraimages
variable tells QDoc to incorporate specific images in the generated documentation.
QDoc will not recognize images used within HTML (or any other markup language). If we want the images to be copied from the directories specified by
imagedirs
(the images in question must be located in these directories) to the output directory, we must specify the images using the
extraimages
变量。
The general syntax is
extraimages.format = image
. The file extension is optional.
例如，在
qtgui.qdocconf
we use a couple of images within the HTML.postheader variable which value is pure HTML. For that reason, these images are specified using the
extraimages
变量：
extraimages.HTML = qt-logo
The
falsehoods
variable defines the truth value of specified preprocessor symbols as false.
The values of the variable are regular expressions (see QRegExp for details). If this variable is not set for a preprocessor symbol, QDoc assumes its truth value is true. The exception is '0', which is always false.
QDoc will recognize, and is able to evaluate, the following preprocessor syntax:
#ifdef NOTYET ... #endif #if defined (NOTYET) ... #end if
However, faced with unknown syntax like
#if NOTYET ... #endif
QDoc will evaluate it as true by default,
unless
the preprocessor symbol is specified within the
falsehoods
variable entry:
falsehoods = NOTYET
另请参阅 定义 .
The
generateindex
variable contains a boolean value that specifies whether to generate an index file when HTML documentation is generated.
By default, an index file is always generated with HTML documentation, so this variable is typically only used when disabling this feature (by setting the value to
false
) or when enabling index generation for the WebXML output (by setting the value to
true
).
The
headerdirs
variable specifies the directories containing the header files associated with the
.cpp
source files used in the documentation.
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
When executed, the first thing QDoc will do is to read through the headers specified in the
headers
variable, and the ones located in the directories specified in the
headerdir
variable (including all subdirectories), building an internal structure of the classes and their functions.
Then it will read through the sources specified in the
sources
, and the ones located in the directories specified in the
sourcedirs
varible (including all subdirectories), merging the documentation with the structure it retrieved from the header files.
If both the
headers
and
headerdirs
variables are defined, QDoc will read through both, first
headers
then
headerdirs
.
In the specified directories, QDoc will only read the files with the
fileextensions
specified in the
headers.fileextensions
variable. The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp, and *.hxx". The files specified by
headers
will be read without taking into account their fileextensions.
另请参阅 headers and headers.fileextensions .
The
headers
variable allows you to specify individual header files in addition to those located in the directories specified by the
headerdirs
变量。
headers = $QTDIR/src/gui/widgets/qlineedit.h \
$QTDIR/src/gui/widgets/qpushbutton.h
When processing the
headers
variable, QDoc behaves in the same way as it does when processing the
headerdirs
variable. For more information, see the
headerdirs
变量。
另请参阅 headerdirs .
The
headers.fileextensions
variable specify the extension used by the headers.
When processing the header files specified in the
headerdirs
variable, QDoc will only read the files with the fileextensions specified in the
headers.fileextensions
variable. In this way QDoc avoids spending time reading irrelevant files.
The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp, and *.hxx.
The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example:
header.fileextensions += *.H
警告： The above assignment may not work as described.
另请参阅 headerdirs .
The
ignorewords
variable is used for specifying a list of strings that QDoc will ignore when resolving hyperlink targets.
QDoc has an auto-linking feature, where linking is attempted for words that resemble C++, QML, or JavaScript entities. Specifically, a string qualifies for auto-linking if it is at least three characters in length, has no whitespace, and it
()
or
::
，或
@
or
_
.
Adding a qualified word to
ignorewords
stops QDoc from linking that word automatically. For example, if the word
OpenGL
is a valid link target (a section,
\page
，或
\externalpage
title), a hyperlink for each occurrence can be avoided with
ignorewords += OpenGL
Linking explicitly with \l continues to work for ignored words.
The
ignorewords
variable was introduced in QDoc 5.14.
The
ignoresince
variable is used for setting a cutoff value for versions passed to the
\since
command. All \since commands that define a version lower than the cutoff are ignored and do not generate output.
The cutoff values are project-specific. The project name can be defined as a subvariable. The default project name is Qt 。例如：
ignoresince = 5.0 ignoresince.QDoc = 5.0
These will ignore \since commands where the major version is 4 or lower and the project is either
QDoc
or undefined.
\since 3.2 # Ignored \since 5.2 # Documented (as 'Qt 5.2') \since QDoc 4.6 # Ignored \since QtQuick 2.5 # Documented
The
ignoresince
variable was introduced in QDoc 5.15.
另请参阅 \since .
The
imagedirs
variable specifies the directories containing the images used in the documentation.
The
images
and
imagedirs
variables are used by the
\image
and
\inlineimage
commands. If both the
images
and
imagedirs
variables are defined, QDoc will search in both. First in
images
, then in
imagedirs
.
QDoc will search through the directories in the specified order, and accept the first matching file it finds. It will only search in the specified directories, not in subdirectories.
imagedirs = $QTDIR/doc/src/images \
$QTDIR/examples
images = $QTDIR/doc/src/images/calculator-example.png
When processing
\image calculator-example.png
QDoc will then see if there is a file called calculator-example.png listed as a value in the
images
variable. If there isn't, it will search in the
imagedirs
variable for:
$QTDIR/doc/src/images/calculator-example.png
If the file doesn't exist, QDoc will look for a file called
$QTDIR/examples/calculator-example.png
You can filter the images in an image directory using the
images.fileextensions
variable. The general idea behind the
images.fileextensions
variable is to enable different image format for different output format.
警告：
The
images.fileextensions
variable's functionality is preliminary since QDoc at this point only supports HTML.
另请参阅 images and images.fileextensions .
The
images
variable allows you to specify individual image files in addition to those located in the directories specified by the
imagedirs
变量。
images = $QTDIR/doc/src/images/calculator-example.png
When processing the
images
variable, QDoc behaves in the same way as it does when processing the
imagedirs
variable. For more information, see the
imagedirs
变量。
另请参阅 imagedirs and images.fileextensions .
The images.fileextensions variable filters the files within an image directory.
The variable's values (the extensions) are given as standard wildcard expressions. The general syntax is:
images.fileextensions.format = *.extension
.
The idea is to enable different image format for different output format.
images.fileextensions.HTML = *.png images.fileextensions.LOUT = *.eps
Then, when processing the \image and \inlineimage commands, QDoc will only search for files with extensions specified in the variable containing the list of output formats.
警告： This is only a preliminary functionality since QDoc at this point only supports HTML.
The default extensions for HTML are *.png, *.jpg, *.jpeg, and *.gif.
You can add a file extension to the filter using '+='. For example:
images.fileextensions.HTML += *.eps
The
语言
variable specifies the language of the source code that is used in the documentation.
Currently, C++ is the only language that QDoc understands. It is also the default language, and doesn't really need to be specified. However, a possible example of a language variable statement:
language = Cpp
This identifies C++ as the language of the Qt source code.
The
locationinfo
boolean variable determines whether detailed location information about each entity is written to
.index
-files and
.webxml
-files (when using the WebXML output format).
Location information consists of the full path and line number of either the declaration or documentation comment block in the source code.
Setting this to
false
turns off location info:
locationinfo = false
默认值为
true
.
The
locationinfo
variable was introduced in QDoc 5.15.
The
macro
variable is used to create your own simple QDoc commands. The syntax is
macro.command = definition
, where the definition is written using QDoc syntax.
A macro variable can be restricted for use in one type of output generation. By appending
.HTML
to the macro name, for example, the macro is only used when generating HTML output.
macro.gui = "\\b" macro.raisedaster.HTML = "<sup>*</sup>"
The first macro defines the \gui command to render its argument using a bold font. The second macro defines the \raisedaster command to render a superscript asterisk, but only when generating HTML.
A macro can also take up to seven parameters:
macro.hello = "Hello \1!"
Parameters are passed to macros the same way as to other commands:
\hello World
When using more than one parameter, or when an argument contains whitespace, enclose each argument in braces:
macro.verinfo = "\1 (version \2)"
\verinfo {QFooBar} {1.0 beta}
A special macro option, match , can be added for additional regular expression pattern matching for expanded macros.
例如，
macro.qtminorversion = "$QT_VER" macro.qtminorversion.match = "\\d+\\.(\\d+)"
This creates a macro \qtminorversion that expands to the minor version based on the QT_VER environment variable.
A macro that defines a match pattern outputs all capture groups (parentheses) concatenated together, or the exact matched string if the pattern does not contain any capture groups.
另请参阅 alias .
The
manifestmeta
variable specifies additional meta-content for the example manifest files generated by QDoc.
见 Manifest Meta Content section for more information.
The
naturallanguage
variable specifies the natural language used for the documentation generated by QDoc.
naturallanguage = zh-Hans
By default, the natural language is
en
for compatibility with legacy documentation.
QDoc will add the natural language information to the HTML it generates, using the
lang
and
xml:lang
属性。
另请参阅 sourceencoding , outputencoding , C.7. The lang and xml:lang Attributes and Best Practice 13: Using Hans and Hant codes .
The
navigation
sub-variables, if defined, set the home page, landing page, C++ classes page, and QML types page that are visible in the generated navigation bar for each page.
In a project with multiple sub-projects (for example, Qt modules), each sub-project typically defines its own landing page while the same home page is used across all sub-projects.
Sub-variables
navigation.homepage
|
Project home page. |
navigation.hometitle
|
(Optional) User-visible title for the home page. Default value is taken from
homepage
.
|
navigation.landingpage
|
Sub-project landing page. |
navigation.landingtitle
|
(Optional) User-visible title for the landing page. Defaults value is taken from
landingpage
.
|
navigation.cppclassespage
|
Top-level page that lists all C++ classes for this (sub-)project. Typically, the title of a \module 页面。 |
navigation.cppclassestitle
|
(Optional) User-visible title for the C++ classes page. Default is "C++ Classes". |
navigation.qmltypespage
|
Top-level page that lists all QML types for this (sub-)project. Typically, the title of a \qmlmodule 页面。 |
navigation.qmltypestitle
|
(Optional) User-visible title for the QML types page. Default is "QML Types". |
例如：
# 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"
The above configuration produces the following navigation bar for
Item
QML type:
Qt 5.10 > Qt Quick > QML Types > Item QML Type
The
outputdir
variable specifies the directory where QDoc will put the generated documentation.
outputdir = $QTDIR/doc/html
locates the generated Qt reference documentation in $QTDIR/doc/html. For example, the documentation of the QWidget class is located in
$QTDIR/doc/html/qwidget.html
The associated images will be put in an
images
子目录。
警告： When running QDoc multiple times using the same output directory, all files from the previous run will be lost.
The
outputencoding
variable specifies the encoding used for the documentation generated by QDoc.
outputencoding = UTF-8
By default, the output encoding is
ISO-8859-1
(Latin1) for compatibility with legacy documentation. When generating documentation for some languages, particularly non-European languages, this is not sufficient and an encoding such as UTF-8 is required.
QDoc will encode HTML using this encoding and generate the correct declarations to indicate to browsers which encoding is being used. The naturallanguage configuration variable should also be specified to provide browsers with a complete set of character encoding and language information.
另请参阅 outputencoding and naturallanguage .
The
outputformats
variable specifies the format(s) of the generated documentation.
Since Qt 5.11, QDoc supports the HTML and WebXML formats; since Qt 5.15, it can also generate the documentation in DocBook. If no
outputformats
are specified, QDoc generates the documentation in HTML (the default format). All output formats can be specified, with dedicated output directories and other settings. For example:
outputformats = WebXML HTML WebXML.nosubdirs = true WebXML.outputsubdir = webxml WebXML.quotinginformation = true
This generates HTML documentation using the default settings, as well as WebXML documentation into output subdirectory webxml .
The
outputprefixes
variable specifies a mapping between types of files and the prefixes to prepend to the HTML file names in the generated documentation.
outputprefixes = QML JS outputprefixes.QML = uicomponents- outputprefixes.JS = uicomponents-
By default, files containing the API documentation for QML types are prefixed with "qml-", and javaScript types with "js-". In the above example, the prefix
"uicomponents"
is used instead for both.
The output prefix is applied to file names for documentation on QML and JS types.
The
outputsuffixes
variable specifies a mapping between types of files and module name suffixes to append to the HTML file names.
outputsuffixes = QML outputsuffixes.QML = -tp
Given a QML module name
FooBar
and the default
output prefix
("qml-"), the file name of the generated HTML page for a QML type
FooWidget
将为
qml-foobar-tp-foowidget.html
.
By default, no suffix is used. The output suffix, if defined, is applied to file names for documentation on QML and JS types, and their respective module pages.
The
outputsuffixes
variable was introduced in QDoc 5.6.
The
qhp
variable is used to define the information to be written out to Qt Help Project (
qhp
) files.
见 创建帮助工程文件 chapter for information about this process.
The
sourcedirs
variable specifies the directories containing the
.cpp
or
.qdoc
files used in the documentation.
sourcedirs += .. \
../../../examples/gui/doc/src
When executed, the first thing QDoc will do is to read through the headers specified in the
header
variable, and the ones located in the directories specified in the
headerdir
variable (including all subdirectories), building an internal structure of the classes and their functions.
Then it will read through the sources specified in the
sources
, and the ones located in the directories specified in the
sourcedirs
variable (including all subdirectories), merging the documentation with the structure it retrieved from the header files.
If both the
sources
and
sourcedirs
variables are defined, QDoc will read through both, first
sources
then
sourcedirs
.
In the specified directories, QDoc will only read the files with the
fileextensions
specified in the
sources.fileextensions
variable. The default extensions are *.c++, *.cc, *.cpp and *.cxx. The files specified by
sources
will be read independent of their fileextensions.
另请参阅 sources and sources.fileextensions .
The
sourceencoding
variable specifies the encoding used for the source code and documentation.
sourceencoding = UTF-8
By default, the source encoding is
ISO-8859-1
(Latin1) for compatibility with legacy documentation. For some languages, particularly non-European languages, this is not sufficient and an encoding such as UTF-8 is required.
Although QDoc will use the encoding to read source and documentation files, limitations of C++ compilers may prevent you from using non-ASCII characters in source code comments. In cases like these, it is possible to write API documentation completely in documentation files.
另请参阅 naturallanguage and outputencoding .
The
sources
variable allows you to specify individual source files in addition to those located in the directories specified by the
sourcedirs
变量。
sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
$QTDIR/src/gui/widgets/qpushbutton.cpp
When processing the
sources
variable, QDoc behaves in the same way as it does when processing the
sourcedirs
variable. For more information, see the
sourcedirs
变量。
另请参阅 sourcedirs .
The
sources.fileextensions
variable filters the files within a source directory.
When processing the source files specified in the
sourcedirs
variable, QDoc will only read the files with the fileextensions specified in the
sources.fileextensions
variable. In this way QDoc avoid spending time reading irrelevant files.
The default extensions are *.c++, *.cc, *.cpp and *.cxx.
The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example:
sources.fileextensions += *.CC
警告： The above assignment may not work as described.
另请参阅 sourcedirs and (sources-variable} {sources}.
The
spurious
variable excludes specified QDoc warnings from the output. The warnings are specified using standard wildcard expressions.
spurious = "Cannot find .*" \ "Missing .*"
makes sure that warnings matching either of these expressions, will not be part of the output when running QDoc. For example would the following warning be omitted from the output:
src/opengl/qgl_mac.cpp:156: Missing parameter name
The
syntaxhighlighting
variable specifies whether QDoc should perform syntax highlighting on source code quoted in the documentation it generates.
syntaxhighlighting = true
will enable syntax highlighting for all supported programming languages.
The
tabsize
variable defines the size of a tab character.
tabsize = 4
will give the tab character the size of 4 spaces. The default value of the variable is 8, and doesn't need to be specified.
The
tagfile
variable specifies the Doxygen tag file to be written when HTML is generated.
The
version
variable specifies the version number of the documented software.
version = 5.6.0
When a version number is specified (using the
version
or
versionsym
variables in a
.qdocconf
file), it is accessible through the corresponding \version command for use in the documentation.
警告： The \version command's functionality is not fully implemented; currently it only works within raw HTML code.
另请参阅 versionsym .
The
versionsym
variable specifies a C++ preprocessor symbol that defines the version number of the documented software.
versionsym = QT_VERSION_STR
QT_VERSION_STR is defined in qglobal.h as follows
#define QT_VERSION_STR "5.14.1"
When a version number is specified (using the
version
or
versionsym
variables in a
.qdocconf
file), it is accessible through the corresponding \version command for use in the documentation.
警告： The \version command's functionality is not fully implemented. Currently, it only works within raw HTML code.
另请参阅 \version .
The
warninglimit
variable sets the maximum number of documentation warnings allowed. If this limit is exceeded, QDoc continues as normal but exits with the warning count as the error code. If the limit was not exceeded or
warninglimit
was not defined, QDoc process exits with 0, assuming there were no other critical errors.
设置
warninglimit
to
0
means failure on any warning.
注意：
By default, QDoc does not enforce the warning limit. Enable it with
warninglimit.enabled = true
or by defining the
QDOC_ENABLE_WARNINGLIMIT
环境变量。
例如，
# Fail the documentation build if we have more than 100 warnings warninglimit = 100 warninglimit.enabled = true
The
warninglimit
variable was introduced in Qt 5.11.