Grantlee Gems: Creating documentation for Qt Assistant

One valuable feature of any software library is easily accessible documentation. Qt Assistant provides a good way to browse the Qt documentation.

For everyone else doxygen generates API documentation and can even generate documentation which can be used with Qt Assistant. Using a suitable doxytag file it is also possible for doxygen to create external links to the Qt documentation.

However, depending on where the documentation is accessed, the external links might have to be different. When the documentation is viewed on the internet, the external links should end on the online Qt documentation. When viewed in Qt Assistant though, links to Qt classes should open the correct link in the assistant, not an external web browser.

It turns out that by using qthelp://com.trolltech.qt/qdoc/ as the prefix for the links in Assistant, Qt references will be opened in the latest version of Qt in assistant. There is still a problem of using different links for the online documentation though.

The way I do this in Grantlee is to generate the documentation twice. Once with each target for the links. Two Doxyfiles are created for the two external link configurations using a cmake file as a template.

The configure_file CMake command is then used to create the two appropriate Doxyfiles. A nice benefit of doing it this way is that the version can also be injected into the Doxyfile, so the version of your library needs to be specified in only one place, the CMakeLists.txt file. There’s no need to also maintain a version number in the Doxyfile or the Mainpage.dox file.

configure_file only allows simple string substitution, not loops or conditionals. Sounds like I need to port CMake to Grantlee :).

5 Responses to “Grantlee Gems: Creating documentation for Qt Assistant”

  1. Marc Says:

    You don’t need to create the whole documentation HTML twice. Doxygen has support for changing the base URLs after the fact:

  2. simon Says:

    where did you get the doxytag file for recent Qt versions? I tried creating it on windows from the documentation delifered with the sources, but that was compiled html and doxytag didn’t understand it.

  3. steveire Says:

    @simon: I used the doxytag file from the tarballs on

    For example, from here:

  4. Grantlee version 0.1.7 now available « Steveire's Blog Says:

    […] in assistant. The web version opens links to the GNU generated stl documentation on the web using familiar scripts. Opening STL documentation in assistant linked from […]

  5. Last week in Qt development (week 24 2012) - KDAB Says:

    […] qdoc is the tool used to generate documentation for the official Qt modules. The tool processes the C++ and QML source code and comments along with additional pages of input to generate the documentation distributed with Qt. For third parties, doxygen is commonly used to generate documentation using similar markup. It is also possible to generate documentation for Qt assistant using doxygen. […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: