Generic Configuration Variables | Qt 6.11

- Qt 6.11
- QDoc Manual
- The QDoc Configuration File
- Generic Configuration Variables
- Qt 6.11.2 Reference Documentation

The QDoc Configuration File ◦ Creating Help Project Files

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

## codelanguages

The `codelanguages` variable specifies a list of source code languages not recognized by QDoc that can be used within \code ... \endcode blocks. This enables blocks of code to be written in languages that QDoc cannot parse, and HTML to be generated that can be highlighted or processed by other tools.

     codelanguages = Python Rust Java Swift "C#"

Since QDoc can handle C++ (Cpp), QML and text, these languages do not need to be specified in this list. Language names containing special characters, such as C#, need to be quoted with double quotes when included in this list.

The `codelanguages` variable was introduced in QDoc 6.11 to enable online Qt documentation to use syntax highlighting for a subset of the languages supported by highlight.js.

See also \code.

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

## documentationinheaders

Set `documentationinheaders = true` to instruct QDoc to parse documentation comments also in header files when generating documentation for C++-based projects.

Warning: In large code bases, this may impact QDoc's processing time. Therefore, you shouldn't set this flag unless you need it.

This feature was introduced to QDoc with Qt 6.9.

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

Note: It is possible to override `examplesinstallpath` for an individual \example using the \meta command.

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.

## examples.warnaboutmissingimages

While processing example documentation, QDoc may emit warnings if an example doesn't contain any images. This warning can be disabled by setting the following configuration variable in the .qdocconf file for the project:

`examples.warnaboutmissingimages = false`

This configuration variable was introduced to QDoc with Qt 6.9.

See also examples.warnaboutmissingprojectfiles.

## examples.warnaboutmissingprojectfiles

While processing example documentation, QDoc may emit warnings if an example doesn't contain a project file. This warning can be disabled by setting the following configuration variable in the .qdocconf file for the project:

`examples.warnaboutmissingprojectfiles = false`

This configuration variable was introduced to QDoc with Qt 6.9.

See also examples.warnaboutmissingimages.

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

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

Warning: The above assignment may not work as described.

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.

Note: For Qt documentation projects, the build system typically provides the required include paths as command line arguments when invoking QDoc.

See also moduleheader.

## includeprivate

Use `includeprivate` to include private C++ class members in your documentation. QDoc normally excludes private functions, types, and variables from generated documentation.

To include all private members, set `includeprivate` to `true`:

     includeprivate = true

You can also enable specific member types:

     # Include only private functions
     includeprivate.functions = true

     # Include only private types (classes, enums, typedefs)
     includeprivate.types = true

     # Include only private variables
     includeprivate.variables = true

Specific settings override the global setting. For example:

     includeprivate = true
     includeprivate.types = false

This configuration includes private functions and variables but excludes private types.

Note: Document private members only when you need to explain internal APIs and implementation details. Avoid exposing implementation details that users don't need.

QDoc introduced `includeprivate` in Qt 6.11.

## internalfilepatterns

The `internalfilepatterns` variable specifies file path patterns that identify internal implementation files. Classes declared in files matching these patterns are automatically marked as Internal, along with all their members (properties, functions, enums, nested types). Free functions, enums, and typedefs at file scope are not affected by this setting.

When showinternal is `false` (the default), these entities are excluded from documentation validation. When `showinternal` is `true`, they are included in the documentation but retain their Internal status, allowing generators to style them differently (such as adding visual indicators for internal APIs).

This is useful for private implementation headers that contain classes not part of the documented public interface. In Qt, this includes private headers ending with `_p.h`.

### Pattern Syntax

The patterns support two syntaxes:

- Shell-style glob patterns: Simple wildcards where `*` matches any characters and `?` matches exactly one character. Glob patterns are matched against the filename only, not the full path, making them ideal for patterns such as `*_p.h`.
- Regular expressions: For path-based matching, use regex syntax. Any pattern containing regex metacharacters (`^$[]{}()|+\\.`) is treated as a regular expression and matched against the full normalized file path.

Patterns are matched with forward slashes (`/`) as directory separators. QDoc normalizes path separators internally, so always use `/` in patterns regardless of platform.

When a class is marked as Internal due to its file location, the Internal status automatically propagates to all its members through the node hierarchy.

Example - Qt Convention (glob):

     internalfilepatterns = *_p.h

Matches any file ending with `_p.h` at any directory depth.

Example - Multiple Filename Patterns (glob):

     internalfilepatterns = *_p.h *_impl.h *_pch.h

Matches files ending with `_p.h`, `_impl.h`, or `_pch.h`.

Note: Glob patterns will not work for directory matching, as globs only see the filename. For directory-based patterns, use regex instead.

Example - Directory-Based Match (regex):

     internalfilepatterns = .*/internal/.*\.h

Matches any `.h` file in any `internal` directory at any depth.

Example - Multiple Patterns:

     internalfilepatterns = *_p.h .*/private/.*\.h

Combines glob patterns for simple cases with regex for complex paths.

QDoc introduced `internalfilepatterns` in Qt 6.11.

See also: excludedirs and excludefiles.

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

## imagesoutputdir

The `imagesoutputdir` variable controls the name of the subdirectory, under the output directory, that QDoc uses to store images.

The default value for `imagesoutputdir` is images.

Image files passed as an argument to `\image` and `\inlineimage` commands are copied to this directory.

Setting a custom output directory for images is useful for multi-module documentation builds where multiple documentation projects are configured to use a shared output directory. For example, with the following (shared) configuration:

     imagesoutputdir = images/${project}

Each documentation project in the build uses `<outputdir>/images/<project name>` to store images, thus avoiding identically-named image files overwriting each other.

This variable was introduced to QDoc with Qt 6.11.

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

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

## logwarnings

The `logwarnings` boolean variable determines whether QDoc writes warning messages to a log file in addition to stderr.

When set to `true`, QDoc creates a log file named `<project>-qdoc-warnings.log` in the output directory and writes all warning messages to this file. Warnings are still also written to stderr as usual.

The log file includes a header with project information and, by default, the command-line arguments used to invoke QDoc for reproducibility.

Setting this to `true` enables warning logging:

     logwarnings = true

The default value is `false`.

This feature is useful for large documentation sets or CI environments where warnings can be numerous and scroll by too quickly to be analyzed systematically.

The `logwarnings` variable was introduced in QDoc 6.11.

### logwarnings.disablecliargs

The `logwarnings.disablecliargs` boolean sub-variable controls whether CLI arguments are omitted from warning log file headers.

     logwarnings.disablecliargs = true

When set to `true`, the command-line arguments are omitted from the log file header, making the log files portable across different environments. This is useful for test suites and CI systems where command-line arguments contain environment-specific paths and temporary directories.

The default value is `false`. The `logwarnings.disablecliargs` variable was introduced in QDoc 6.11.

## macro

The `macro` variable is used to create your own simple QDoc commands. The syntax is `macro.command = definition`. command is limited to a combination of letter and number characters, but no special characters like dash or underscore. 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

`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 page.
`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 page.
`navigation.qmltypestitle` | (Optional) User-visible title for the QML types page. Default is "QML Types".
`navigation.toctitles` (Since QDoc 6.0) | Page title(s) containing a \list structure that acts as a table of contents (TOC). QDoc generates navigation links for pages listed in the TOC, without the need for \nextpage and \previouspage commands, as well as a navigation hierarchy that's visible in the navigation bar (breadcrumbs) for HTML output.
`navigation.toctitles.inclusive` (Since QDoc 6.3) | If set to `true`, page(s) listed in `navigation.toctitles` will also appear in the navigation bar as a root item.
`navigation.trademarkspage` (Since QDoc 6.8) | Title of a page that documents trademarks mentioned in the documentation. See also `\tm` command.

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

### Table of contents and navigation links

If there are one or more pages that act as a table of contents (TOC), list their titles in `navigation.toctitles` to automate the navigational (previous and next page) link generation for all pages listed in a TOC.

QDoc expects a `\list` of links on each TOC page. Nested sub-lists are allowed.

For example,

     \list
         \li \l {Home}
         \li \l {Getting started}
         \li What's new
             \list
                 \li \l {What's new in v1.3} {v1.3}
                 \li \l {What's new in v1.2} {v1.2}
                 \li \l {What's new in v1.1} {v1.1}
             \endlist
     \endlist

Since QDoc version 6.10, also `\generatelist` can appear in the table of contents list:

     \list
         \li \l {Home}
         \li \l {Getting started}
         \li What's new
         \generatelist [descending] whatsnew
     \endlist

Here, the result is similar to the first \list, assuming all three `What's new` pages are part of the same `whatsnew` group.

See also `\ingroup`.

## overloadedsignalstarget

Default: `connecting-overloaded-signals`

The `overloadedsignalstarget` variable specifies the link target used in automatically generated notes for overloaded signals.

When QDoc encounters an overloaded signal, it generates a note with a link to help documentation on connecting to overloaded signals. By default, this links to a target named `connecting-overloaded-signals`.

Projects can customize this to link to their own documentation:

     # Link to a target within the project
     overloadedsignalstarget = signals-guide.html#overloaded-signals

     # Link to external documentation
     overloadedsignalstarget = https://example.com/docs/signals.html#overloaded-signals

The target can be:

- A simple target name (for use with `\target` commands): `connecting-overloaded-signals`
- A relative URL: `signals-guide.html#overloaded-signals`
- An absolute URL: `https://example.com/docs/signals.html#overloaded-signals`

See also overloadedslotstarget.

## overloadedslotstarget

Default: `connecting-overloaded-slots`

The `overloadedslotstarget` variable specifies the link target used in automatically generated notes for overloaded slots.

When QDoc encounters an overloaded slot, it generates a note with a link to help documentation on connecting to overloaded slots. By default, this links to a target named `connecting-overloaded-slots`.

Projects can customize this to link to their own documentation:

     # Link to a target within the project
     overloadedslotstarget = signals-guide.html#overloaded-slots

     # Link to external documentation
     overloadedslotstarget = https://example.com/docs/slots.html#overloaded-slots

The target can be:

- A simple target name (for use with `\target` commands): `connecting-overloaded-slots`
- A relative URL: `signals-guide.html#overloaded-slots`
- An absolute URL: `https://example.com/docs/slots.html#overloaded-slots`

See also overloadedsignalstarget.

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

Warning: When running QDoc multiple times using the same output directory, all files from the previous run will be lost.

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

Warning: The above assignment may not work as described.

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.

Warning: The \version command's functionality is not fully implemented; currently it only works within raw HTML code.

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.

Warning: The \version command's functionality is not fully implemented. Currently, it only works within raw HTML code.

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.

Note: By default, QDoc does not enforce the warning limit. Enable it with `warninglimit.enabled = true` or by defining the `QDOC_ENABLE_WARNINGLIMIT` environment variable.

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.

The QDoc Configuration File ◦ Creating Help Project Files