Creating Help Project Files | Qt 6.10

- Qt 6.10
- QDoc Manual
- The QDoc Configuration File
- Creating Help Project Files
- Qt 6.10.3 Reference Documentation

Generic Configuration Variables ◦ Format-specific Configuration Variables

# Creating Help Project Files

## Overview

Qt Assistant uses a system for managing Qt documentation that requires QDoc to generate inventories of files.

QDoc allows configuration variables to be used to specify which pages are to be used in each documentation set it generates. These are specified as subvariables of the `qhp` variable with each set declared using a unique identifier as a subvariable.

For example, the configuration file for the Qt Quick documentation set specifies information about the set as subvariables with the `qhp.QtQuick` prefix:

     qhp.projects = QtQuick

     qhp.QtQuick.file                = qtquick.qhp
     qhp.QtQuick.namespace           = org.qt-project.qtquick.$QT_VERSION_TAG
     qhp.QtQuick.virtualFolder       = qtquick
     qhp.QtQuick.indexTitle          = Qt Quick
     qhp.QtQuick.indexRoot           =

     qhp.QtQuick.subprojects         = qmltypes classes examples

     qhp.QtQuick.subprojects.qmltypes.title = QML Types
     qhp.QtQuick.subprojects.qmltypes.indexTitle = Qt Quick QML Types
     qhp.QtQuick.subprojects.qmltypes.selectors = qmlclass
     qhp.QtQuick.subprojects.qmltypes.sortPages = true

     qhp.QtQuick.subprojects.classes.title = Classes
     qhp.QtQuick.subprojects.classes.title = C++ Classes
     qhp.QtQuick.subprojects.classes.indexTitle = Qt Quick C++ Classes
     qhp.QtQuick.subprojects.classes.selectors = class fake:headerfile
     qhp.QtQuick.subprojects.classes.sortPages = true

     qhp.QtQuick.subprojects.examples.title = Examples
     qhp.QtQuick.subprojects.examples.indexTitle = Qt Quick Examples and Tutorials
     qhp.QtQuick.subprojects.examples.selectors = fake:example

The documentation set may include one or more subprojects, which are added to the table of contents under the name specified by `title`. The page in the documentation referred to by the `indexTitle` acts as the index page for the subproject. The page types to list under the subproject are specified by `selectors`. The entries are alphabetically sorted if `sortPages` is set to `true`.

### Using Selectors

The `selectors` property specifies which page types are listed under the table of contents entry for a subproject. Multiple selectors can be listed, separated by whitespace.

Note: If a subproject does not define a `selectors` property, all pages in the project are included by default.

Selector | Description
--- | ---
`namespace` | Namespaces
`class` | Classes
`qmltype` | QML Types
`qmlclass` | Alias for `qmltype`.
`module[:name]` | C++ modules or members of the module with a specified name.
`qmlmodule[:name]` | QML modules or members of the module with a specified name.
`doc[:subtype]` | Documentation pages with a specified `subtype`. Multiple subtypes can be listed as a comma-separated list.
`fake` | Alias for `doc`.
`group[:groupname]` | Documentation pages for members of a specified group, as added using the \ingroup groupname command. Multiple group names can be listed as a comma-separated list. (Introduced in QDoc 5.6).
`none` | Selects nothing; only a link to the `indexTitle` is generated. (Introduced in QDoc 6.9).

Available subtypes for the `doc` selector:

Subtype | Description
--- | ---
`example` | Examples
`headerfile` | Header files
`page` | Documentation pages defined with the \page command.

For example, the following configuration would select example pages and pages that include the `\ingroup tutorials` command:

     qhp.QtQuickControls.subprojects = examples
     qhp.QtQuickControls.subprojects.examples.title = Examples and Tutorials
     qhp.QtQuickControls.subprojects.examples.indexTitle = Qt Quick Controls Examples
     qhp.QtQuickControls.subprojects.examples.selectors = doc:example group:tutorials
     qhp.QtQuickControls.subprojects.examples.sortPages = true

### Adding Table of Contents

To create a table of contents for a manual, create a subproject with a `type` property and set it to `manual`. The page in the documentation referred to by the `indexTitle` property must contain a list of links that acts as a table of contents for the whole manual. QDoc will take the information in this list and create a table of contents for the subproject.

For example, the configuration file for Qt Creator defines only one subproject for its documentation, including all the documentation in a single manual:

     qhp.QtCreator.subprojects = manual
     qhp.QtCreator.subprojects.manual.title = Qt Creator Manual
     qhp.QtCreator.subprojects.manual.indexTitle = All topics
     qhp.QtCreator.subprojects.manual.type = manual

In this example, the page entitled "All topics" contains a nested list of links to pages in the documentation which is duplicated in Qt Assistant's Contents tab.

An example of such a list structure:

     /*!
         \page qtcreator-toc.html
         \title All topics

         \list
             \li \l {Installation}
             \li \l {Getting started}
             \list
                 \li \l {Configuring Qt Creator}
                 \li \l {Building and running an example}
             \endlist
             \li \l {Overview}
             \li \l {Tutorials}
                 \generatelist tutorials
             ...
         \endlist
     */

Above, the Getting started topic has two pages as sub-topics. The Tutorials topic is a `\group` page, and a `\generatelist` command is used for listing individual tutorial pages (members of `tutorials` group) as its sub-topics.

Generic Configuration Variables ◦ Format-specific Configuration Variables