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 Doxyfile.in 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🙂.

4 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: http://www.doxygen.nl/installdox_usage.html

  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 api.kde.org.

    For example, from here:
    http://api.kde.org/kdereview-api/kdereview.tar.gz

  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 […]

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s


%d bloggers like this: