Creating Help Project Files

Overview

Starting with Qt 4.4, Qt Assistant uses a different system for managing Qt documentation that requires QDoc to generate inventories of files in a format that is similar to the old style DCF format, but with additional features.

Instead of hard-coding information about the documentation sets for Qt, 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 qch variable with each set declared using a unique identifier as a subvariable.

For example, the configuration file for the Qt documentation defines a Qt documentation set by specifying information about the set as subvariables with the qhp.Qt prefix:

 qhp.Qt.file                = qt.qhp
 qhp.Qt.namespace           = com.trolltech.qt.440
 qhp.Qt.virtualFolder       = qdoc
 qhp.Qt.indexTitle          = Qt Reference Documentation
 qhp.Qt.indexRoot           =
 qhp.Qt.extraFiles          = classic.css images/qt-logo.png
 qhp.Qt.filterAttributes    = qt 4.4.0 qtrefdoc
 qhp.Qt.customFilters.Qt.name = Qt 4.4.0
 qhp.Qt.customFilters.Qt.filterAttributes = qt 4.4.0
 qhp.Qt.subprojects         = classes overviews examples
 qhp.Qt.subprojects.classes.title = Classes
 qhp.Qt.subprojects.classes.indexTitle = Qt's Classes
 qhp.Qt.subprojects.classes.selectors = class
 qhp.Qt.subprojects.overviews.title = Overviews
 qhp.Qt.subprojects.overviews.indexTitle = All Overviews and HOWTOs
 qhp.Qt.subprojects.overviews.selectors = fake:page,group,module
 qhp.Qt.subprojects.examples.title = Tutorials and Examples
 qhp.Qt.subprojects.examples.indexTitle = Qt Examples
 qhp.Qt.subprojects.examples.selectors = fake:example
 

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 = Qt Creator Manual
 qhp.QtCreator.subprojects.manual.type = manual

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