Generic Configuration Variables | QDoc Manual 5.9

Qt 5.9 | QDoc Manual | Generic Configuration Variables

Qt 5.9.3 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.

## alias

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.

See also macro.

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

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 `defines` 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 -Dconsoleedition qtgui.qdocconf

In this case the -D option ensures that the `consoleedition` preprocessor symbol is defined when QDoc processes the source files defined in the qtgui.qdocconf file.

See also falsehoods and \if.

## edition

The `edition` variable specifies which modules are included in each edition of a package, and provides QDoc with information to provide class lists for each edition.

This feature is mostly used when providing documentation for Qt packages.

The `edition` variable is always used with a particular edition name to define the modules for that edition:

      edition.Console      = QtCore QtNetwork QtSql QtXml
      edition.Desktop      = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \
                             QtDesigner QtAssistant Qt3Support QAxContainer \
                             QAxServer
      edition.DesktopLight = QtCore QtGui Qt3SupportLight

In the above examples, the `Console` edition only includes the contents of four modules. Only the classes from these modules will be used when the generatelist command is used to generate a list of classes for this edition:

      \generatelist{classesbyedition Console}

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

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

The general syntax is `extraimages.format = image`. The file extension is optional.

For example, in 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` variable:

      extraimages.HTML = qt-logo

See also images and imagedirs.

## falsehoods

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

If this variable is not set for a preprocessor symbol, QDoc assumes its truth value is true. The exception is '0', which value always is 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 default extensions are *.ch, *.h, *.h++, *.hh, *.hpp, and *.hxx". 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.

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

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.

Warning: The `images.fileextensions` variable's functionality is preliminary since QDoc at this point only supports HTML.

See also images and images.fileextensions.

## images

The `images` variable allows you to specify individual image files in addition to those located in the directories specified by the `imagedirs` variable.

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

See also imagedirs and images.fileextensions.

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

Warning: 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

See also imagedirs and images.

## language

The `language` 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.

## 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. By appending `.DITAXML` to the macro name, the macro is only used when generating DITA XML.

      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}

See also alias.

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

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

## 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 of the generated documentation.

Currently, QDoc only supports the HTML format. It is also the default format, and doesn't need to be specified.

## outputprefixes

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.

## outputsuffixes

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 would be `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.

## qhp

The `qhp` variable is 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.

## 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 default extensions are *.c++, *.cc, *.cpp and *.cxx. 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 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

Warning: The above assignment may not work as described.

See also sourcedirs and (sources-variable} {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   "4.0.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.

The QDoc Configuration File ◦ Creating Help Project Files