Generic Configuration Variables

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.

codeindent

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.

codeprefix, codesuffix

The codeprefix and codesuffix variables specify a pair of strings that each code snippet is enclosed in.

defines

The defines variable specifies the C++ preprocessor symbols that QDoc will recognize and respond to.

When a preprocessor symbol is specified using the defines variable, you can also use the \if command to enclose documentation that only will be included if the preprocessor symbol is defined.

defines = QT_GUI_LIB

This ensures that QDoc will process the code that requires these symbols to be defined. For example:

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

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.

See also falsehoods and \if.

depends

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 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 $QT_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 = *

See also indexes, project, and url.

exampledirs

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.

See also examples.

examples

The examples variable allows you to specify individual example files in addition to those located in the directories specified by the exampledirs variable.

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

See also exampledirs.

examplesinstallpath

The examplesinstallpath variable sets the root path for this project's examples under the installed example directory.

Assuming a root install path of QT_INSTALL_EXAMPLES for all examples, then the path

<QT_INSTALL_EXAMPLES>/<examplesinstallpath>/<example_path>

will be used to refer to a path of a single example within this documentation project. These paths are recorded in the example manifest file, read by Qt Creator.

To ensure correct paths, examplesinstallpath must match with one of the directories listed in exampledirs. The path passed as an argument for each \example command is relative to the path in exampledirs.

For example:

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

examplesinstallpath = mymodule

And given a following \example command:

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

Then, the path mymodule/basic/hello is recorded in the manifest file for this example.

See also: exampledirs, \example, and \meta.

examples.fileextensions

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

See also headers.fileextensions.

excludedirs

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 variables.

For example:

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.

See also excludefiles.

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"

See also excludedirs.

extraimages

The extraimages variable tells QDoc to incorporate specific images in the generated documentation.

QDoc automatically copies an image file from imagedirs to the output directory if it's referenced by the \image or \inlineimage command. If you want to copy additional images, you must specify them using the extraimages variable.

The general syntax is format.extraimages = image.

For a contextualized example, refer to the description of the HTML.postheader variable.

Example:

HTML.extraimages = images/qt-logo.png

See also images and imagedirs.

falsehoods

The falsehoods variable defines the truth value of specified preprocessor symbols as false.

The values of the variable are regular expressions (see QRegularExpression 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

See also defines.

generateindex

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).

headerdirs

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 files specified by headers will be read without taking into account their fileextensions.

See also headers and headers.fileextensions.

headers

The headers variable allows you to specify individual header files in addition to those located in the directories specified by the headerdirs variable.

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 variable.

See also headerdirs.

headers.fileextensions

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

See also headerdirs.

includepaths

The includepaths variable is used for passing additional include paths to the Clang parser that QDoc uses for parsing C++ code for documentation comments.

The variable accepts a list of paths, prefixed with -I (include path), -F (macOS framework include path), or -isystem (system include path). If a prefix is omitted, -I is used by default.

Paths relative to the current .qdocconf file are resolved into absolute paths. Paths that do not exist in the file system are ignored.

See also moduleheader.

ignorewords

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++ or QML entities. Specifically, a string qualifies for auto-linking if it is at least three characters in length, has no whitespace, and it

• is a camelCase word, that is, it contains at least one uppercase character at index greater than zero, or
• contains the substring () or ::, or
• contains at least one special character, @ 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, or \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.

ignoresince

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. For example:

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.

See also \since.

imagedirs

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

language

The language variable specifies the language of the source code that is used in the documentation. Specifically, it defines the default language for parsing source code within \code .. \endcode blocks.

language = Cpp

The default language is C++ (Cpp), and doesn't need to be explicitly specified. If the code snippets in the documentation consist mainly of QML code, set QML as the default:

language = QML

See also code-command[\code}.

locationinfo

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

The default value is true.

The locationinfo variable was introduced in QDoc 5.15.

macro

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.key              = "\\b"
macro.raisedaster.HTML = "<sup>*</sup>"

The first macro defines the \key 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.

For example,

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.

For more information about pre-defined macros, see Macros.

manifestmeta

The manifestmeta variable specifies additional meta-content for the example manifest files generated by QDoc.

See the Manifest Meta Content section for more information.

moduleheader

The moduleheader variable defines the name of the module header of a documented C++ module.

Projects that document C++ APIs require a module-level header that includes all public classes, namespaces and header files for the module. The Clang parser in QDoc uses this file to build a pre-compiled header (PCH) for the module to increase the speed of parsing source files.

By default, the project name is used also as the module header name.

project = QtCore

With the above project name, QDoc searches a module header QtCore in all known include paths; first using the paths passed as command line arguments, then the paths listed in the includepaths variable.

QDoc will issue a warning if the module header is not found. It will then attempt to build an artificial module header based on the headers listed in the headerdirs variable.

For Qt documentation projects, the build system typically provides QDoc with correct include paths to locate the module header, provided that the project variable is set correctly. The moduleheader variable provides an alternative file name for QDoc to search for.

If the project contains no C++ documentation, QDoc should be instructed to skip generating a PCH by setting moduleheader to an empty string:

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

See also includepaths and project.

naturallanguage

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 attributes.

See also sourceencoding, outputencoding, C.7. The lang and xml:lang Attributes and Best Practice 13: Using Hans and Hant codes.

navigation

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

For example:

# 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

outputdir

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 subdirectory.

outputencoding

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.

See also outputencoding and naturallanguage.

outputformats

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.

outputprefixes

The outputprefixes variable specifies a mapping between types of files and the prefixes to prepend to the output file names in the generated documentation.

QDoc supports adding an output prefix to the file names of QML type, C++ class, namespace, and header file reference pages.

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

By default, files containing the API documentation for QML types are prefixed with qml-. In the above example, the prefix uicomponents- is used instead.

Likewise, C++ type documentation pages are prefixed with components- in the above example. By default, C++ type pages have no prefix.

outputsuffixes

The outputsuffixes variable specifies a mapping between types of files and suffixes to apply to the module or type name as they appear in the output file names.

QDoc supports adding an output suffix to the file names of module pages, QML type, C++ class, namespace, and header file reference pages.

By default, no suffix is used. The QML output suffix, if defined, is applied as a suffix to the module name as it appears in the file names of QML type and QML module pages.

File names for C++ types do not include the module name. The CPP output suffix, if defined, is applied as a suffix for the type name.

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

With the definitions above, given a QML module name FooBar and the default output prefix (qml-), the name of the generated file for a QML type FooWidget is qml-foobar-tp-foowidget.html.

Likewise, for a C++ class QFoobar, QDoc generates qfoobar-tp.html.

The outputsuffixes variable was introduced in QDoc 5.6.

qhp

The qhp sub-variables are used to define the information to be written out to Qt Help Project (qhp) files.

See the Creating Help Project Files chapter for information about this process.

Since QDoc 6.6, setting the base qhp variable to true means that a valid help project configuration is expected:

qhp = true

Then, if a project configuration did not define qhp.projects, QDoc issues a warning. This is useful for ensuring that all documentation projects with a shared top-level .qdocconf file (as in Qt) are configured correctly.

To turn off the warning, set the variable to false.

sourcedirs

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 files specified by sources will be read independent of their fileextensions.

See also sources and sources.fileextensions.

sourceencoding

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.

See also naturallanguage and outputencoding.

sources

The sources variable allows you to specify individual source files in addition to those located in the directories specified by the sourcedirs variable.

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 variable.

See also sourcedirs.

sources.fileextensions

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, *.cxx, *.mm, *.qml and *.qdoc.

The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example:

sources.fileextensions += *.CC

See also sourcedirs and sources.

spurious

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

syntaxhighlighting

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.

tabsize

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.

tagfile

The tagfile variable specifies the Doxygen tag file to be written when HTML is generated.

version

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.

See also versionsym.

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.

See also \version.

warninglimit

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.

Setting the warninglimit to 0 means failure on any warning.

For example,

# 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.