Checklist for Adding Documentation for a New Module

When you submit a new add-on module for Qt, you should also submit documentation for it. You can ask the Qt documentation team for help and reviews. This checklist describes the tasks you have to do to get the module documentation correctly built and included in the Qt reference documentation package. Make sure that you make all the changes in the same branch, usually, dev.

• Create the necessary files and folders, as described in Qt Documentation Structure.

• Set up the project files to create the "make docs" target. For a normal Qt module, this step is done by adding QMAKE_DOCS in the .pro file.

#in qtquickcontrols/src/controls/controls.pro

QMAKE_DOCS = $$PWD/doc/qtquickcontrols.qdocconf #the qdocconf file
load(qml_plugin) #the QMAKE_DOCS should be before the load() command

• Build the documentation for your module with the make docs (or nmake docs) command to check that it compiles and that it looks correct. Pay attention to the errors that qdoc prints out, as they tell you if some code elements have not been documented or if there are errors in documenting them. For example, it is easy to forget to modify documentation for functions that are located in the header files when the functions change. At this point, you might still receive error messages about linking to other modules.

• Check that the <module>.qdocconf file contains the depends variable and that all the modules that you link to in the documentation are listed as values of the variable. You always have to list qtdoc and qtcore.

• Build the documentation for your module to check that the links to other modules work correctly and qdoc does not display any more error messages.

• When you build the documentation successfully with the make docs command, a Qt help file (.qch) is created for the module. Add the help file to Qt Creator and open it to make sure that it looks correct.

• To check that the module's examples are listed in Qt Creator, open the Examples tab in the Welcome mode and search for the examples. If they are not found, try re-launching Qt Creator with the following command:

QTC_DEBUG_EXAMPLESMODEL=1 ./qtcreator &> examples.log

Then open the Examples tab again, and check the contents of examples.log. This may provide useful information about what went wrong.

• Add your module to the table that lists the Qt Add-ons. The source for the table is located in qtdoc/doc/src/qtmodules.qdoc.

• For the link to your module to work, you must also add the module to the depends variable in qtdoc/doc/config/qtdoc.qdocconf.

• Build the documentation for the whole branch (or at least the qtdoc module) to check that the link to your module works correctly.

• Be familiar with the global templates in qtbase/doc/global. C++ macros that QDoc ignores are there as well as additional variables that all of Qt 5 modules inherit are there.

• The navigation bar is set with the navigation variables in the qdocconf file. The page titles of the C++ class, QML type, and landing pages are used to set the navigation bar entries. For an example, view Qt Multimedia's qdocconf file.