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