Supporting Derived Projects | Qt 6.11

- Qt 6.11
- QDoc Manual
- The QDoc Configuration File
- Supporting Derived Projects
- Qt 6.11.2 Reference Documentation

Format-specific Configuration Variables ◦ Example Manifest Files

# Supporting Derived Projects

Some configuration variables allow you to use QDoc to support Qt-based projects. They allow your project to contain links to the online Qt documentation, which means that QDoc will be able to create links to the class reference documentation, without any explicit linking command.

## description

The description variable holds a short description of the associated project.

See also project.

## indexes

The `indexes` variable defines a set of paths to index files to load.

     indexes = \
         $QT_INSTALL_DOCS/qtcore/qtcore.index \
         $SOME_OTHER_PROJECT/doc/foo.index

The `indexes` variable provides an alternative to depends for defining project's dependencies. As direct paths are provided, no `-indexdir` command line option(s) are required when invoking QDoc.

It is possible to define dependencies using either variable. Qt documentation only uses the `depends` variable.

See also depends, project and url.

## productname

Use the `productname` variable if the name of the product being documented is different from the name of the documentation `project` This is particularly useful for larger documentation sets that consist of multiple documentation projects and/or modules, as it allows QDoc to generate the product name instead of project name in certain contexts, such as the `\since` command.

For example, Qt defines Qt as the `productname`, while each individual module defines its own `project` name. This allows authors to use the shorthand notation for the `\since` command.

This configuration variable was introduced to QDoc with Qt 6.9.

See also `\since`.

## project

The `project` variable provides a name for the project associated with the `.qdocconf` file. This is a mandatory variable that all projects must set.

The project's name is used to form a file name for the associated project's index file.

     project = QtCreator

This will cause an index file called `qtcreator.index` to be created.

If the project name contains whitespace or special characters, these are replaced with dashes ('-') in the generated index file name.

See also depends, indexes, and description.

## projectroot

The `projectroot` variable sets the project root directory for relative path calculation in warning logs.

     projectroot = /path/to/project/root

QDoc uses the following priority order to determine the project root:

1. `QDOC_PROJECT_ROOT` environment variable
2. `projectroot` configuration variable
3. If neither is set, absolute paths are used

When a project root is set, QDoc converts absolute file paths to relative paths in warning log files. This makes logs portable across different build environments.

Qt's build system automatically sets `QDOC_PROJECT_ROOT`, so you typically don't need to set `projectroot` manually.

For standalone QDoc usage, setting `projectroot` enables portable warning logs:

     projectroot = /home/user/myproject
     logwarnings = true

The `projectroot` variable was introduced in QDoc 6.11. See also logwarnings.

## url

The `url` variable holds the base URL for the documentation associated with the current project.

The URL is stored in the generated index file for the project. When we use the index on its own, QDoc will use this as the base URL when constructing links to classes, functions, and other things listed in the index.

     project     = QtCore
     description = Qt Core Reference Documentation
     url         = https://doc.qt.io/qt/

     ...

This ensures that whenever QDoc generates references to entities in the Qt Core module, the base URL is `https://doc.qt.io/qt/`.

See also depends, indexes and url.examples.

## url.examples

The `url.examples` variable holds the base URL for the examples associated with the current project.

If defined, a link to the example project directory is generated at the end of each example documentation page. The `url.examples` variable refers to the root directory of the examples related to this project; it can be a link to an online repository (starting with http:// or https://), or to the local file system (`file://`).

If `url.examples` is not defined, QDoc will output a list of example's files and images instead.

For example, given these definitions:

     url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/"
     examplesinstallpath = corelib

Then, for the following \example command:

     /*!
         \example threads/semaphores
         ...
     */

QDoc generates a link to `https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores`.

If the URL contains more components (for example, a query string) after the example path, \1 can be used as a placeholder for the path:

     url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/\1?h=$QT_VER"
     examplesinstallpath = corelib

Given the same \example command as above and assuming that `$QT_VER` expands to `5.13`, the generated URL is `https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores?h=5.13`.

`url.examples` variable was introduced in QDoc version 5.13.

See also url, examplesinstallpath, and \example.

## url.sources

The `url.sources` variable holds the base URL for the C++ source code associated with the current project. This is a URL for viewing the project's sources in a repository, for example, on github.com.

Enable the source links by setting `url.sources.enabled` to `true`. When enabled, QDoc generates a link to a declaration in the synopsis (signature) of each documented C++ entity in its Detailed description section.

In addition, define the root directory of the sources with `url.sources.rootdir`. The generated link is composed of the base URL (`url.sources`) and the path of the source file, relative to `url.sources.rootdir`.

If the URL contains more components after the path (for example, a query string specifying a branch), \1 acts as a placeholder for the path. Similarly, \2 acts as a placeholder for the line number.

`url.sources.linktext` sets the user-visible link text for source links. By default, the link text is an empty string; use the `a.srclink` CSS selector to style the links in the HTML output.

For example, with the following configuration in `qtbase/src/gui/doc/qtgui.qdocconf`:

     url.sources = "https://code.qt.io/cgit/qt/qtbase.git/tree/\1?h=$QT_VER#n\2"
     url.sources.rootdir = ../../..    # root of the `qtbase` repository
     url.sources.linktext = "(source)"
     url.sources.enabled = true

QDoc will generate links to code.qt.io for each documented C++ entity, specific to the branch defined with the `QT_VER` environment variable.

The `url.sources` variable was introduced to QDoc with Qt 6.10.

## usealttextastitle

In some cases, it's desirable to provide a "tooltip" for images when rendered in graphical browsers. QDoc offers a way to do this, where the alt text given as an optional string to the `\image` command is also used as the title attribute for the image. Enable this behavior by setting the this variable with `usealttextastitle = true` in your QDoc configuration file.

This configuration variable was introduced to QDoc with Qt 6.9.

## How to Support Derived Projects

This feature makes use of the comprehensive indexes generated by QDoc when it creates the Qt reference documentation.

For example, qtgui.qdocconf (the configuration file for Qt GUI) contains the following variable definitions:

     project     = QtGui
     description = Qt GUI Reference Documentation
     url         = https://doc.qt.io/qt/

     ...

The project variable name is used to form a file name for the index file; in this case the `qtgui.index` file is created. The url is stored in the index file. Afterwards, QDoc will use this as the base URL when constructing links to classes, functions, and other things listed in the index.

See also depends, indexes, project, and url.

Format-specific Configuration Variables ◦ Example Manifest Files