The QDoc Configuration File

Before running QDoc, you must create a QDoc configuration file to tell QDoc where to find the source files that contain the QDoc comments. The pathname to your configuration file is passed to QDoc on the command line:

/current/dir$ ../../bin/qdoc ./config.qdocconf

General Description

The configuration file is a list of entries of the form "variable = value". Using the configuration variables, you can define where QDoc should find the various source files, images and examples, where to put generated documentation etc. The configuration file can also contain directives like include. For an example, see minimum.qdocconf.

You can also use configuration variables to get QDoc to support derived projects, i.e QDoc can generate links in your project's documentation to elements in the Qt online documentation. See the Supporting Derived projects section.

A valid configuration variable name can include upper and lower case letters, numbers, and an underscore, '_'.

The value of a configuration variable can be set using either '=' or '+='. The difference is that '=' overrides the previous value, while '+=' adds a new value to the current one.

Values of some configuration variables are interpreted as a list of strings, for example: sourcedirs, while others are treated as a single string. Double quotes around a value string are optional, but including them allows you to use special characters like '=' and ' " ' within the value string, for example:

HTML.postheader = "<a href=\"index.html\">Home</a>"

If an entry spans many lines, use a backslash at the end of every line but the last:

sourcedirs = kernel tools widgets

This can be written as:

sourcedirs = kernel \
             tools \
             widgets

If a value spans multiple lines but is interpreted as a single string, the lines are joined with spaces.

Expansion of Configuration Values

QDoc supports expanding environment variables within configuration files. For example, Qt modules rely on the environment variable QT_INSTALL_DOCS to include definitions related to all Qt module documentation projects:

include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)

A variable to expand is prefixed with '$'. To use the literal character '$' within a value string, escape it with a backslash: '\$'.

Since QDoc 6.0, values can be expanded also from other configuration variables. In addition to the $variable syntax, also ${variable} is valid. The latter eliminates the need to separate the variable name with whitespace or non-variable characters. For example:

baseurl = https://doc.qt.io/
...
url = ${baseurl}qtcreator

If the target variable refers to a list of strings, they will be joined using spaces in the expanded value:

vars = foo \
       bar \
       baz

items = "Items: $vars"          # Expands to "Items: foo bar baz"

Controlling which character is used for joining the string list is also possible:

items = "Items: ${vars,|}"      # Expands to "Items: foo|bar|baz"
items = "Items: ${vars,,}"      # Expands to "Items: foo,bar,baz"
items = "Items: ${vars,}"       # Expands to "Items: foobarbaz"

As the expansion is performed after reading in all variables, the order in which they are defined does not matter.

Expanding Environment Variables

When expanding environment variables, the ${variable} syntax has different behavior compared to $variable. The former expands the content of the variable in place to be parsed as part of the configuration file, while the latter simply assigns the content as a value for the current configuration variable. This has implications if the environment variable contains a list of elements separated by whitespace, or other formatting recognized by QDoc.

For example, if the value of an environment variable SRCDIRS is "../src/a ../src/b", then

sourcedirs  = $SRCDIRS      # Fail - value is interpreted as a single path.
sourcedirs  = ${SRCDIRS}    # Ok - whitespace is used as a delimiter.

Configuration Variables

Variable List

• defines
• depends
• documentationinheaders (technical preview)
• exampledirs
• examples
• examplesinstallpath
• examples.fileextensions
• examples.warnaboutmissingimages
• examples.warnaboutmissingprojectfiles
• excludedirs
• excludefiles
• extraimages
• falsehoods
• headerdirs
• headers
• headers.fileextensions
• HTML.footer
• HTML.postheader
• HTML.style
• includepaths
• ignorewords
• ignoresince
• imagedirs
• indexes
• language
• locationinfo
• macro
• manifestmeta
• moduleheader
• navigation
• outputdir
• outputformats
• outputprefixes
• outputsuffixes
• productname
• project
• sourcedirs
• sources
• sources.fileextensions
• spurious
• tabsize
• url
• url.examples
• version
• versionsym
• warninglimit

Categories

• Generic Configuration Variables
• Format-specific Configuration Variables

Configuration File Examples

• A minimum configuration file: minimum.qdocconf
• The Qt configuration file: qtgui.qdocconf