Dear Readers!

If you are a Qt programmer, then it is also very likely that you use Qt Creator and its built in help system, including the popup text that allows you to browse between the different overloads of a particular function, which latter I find to be a particularly useful feature. Despite the fact that an extensive documentation for Qt itself is available for offline browsing within the IDE (if you installed the Qt documentation package as well), sometimes this is just not enough, especially when one creates mixed library projects. Since recently I found myself to be in a similar situation, where Qt serves as the main GUI framework, but the underlying image processing work is done by OpenCV library (which in addition uses quite a few STL features), I started to look for ways to extend the existing function recognition capabilities of Qt Creator with other libraries, as I found the workflow quite a bit better when one can rely on this feature. After browsing a while here and there over the internet, I found a solution, which I will share here as well for convenience’s sake.

The main thing that needs to be understood trying to achieve this, is that Qt Creator can only use its own binary documentation format, a .qch file. Sometimes such a file is already available online, like for the C++ standard library as provided by volunteers, but in other cases the qch file needs to be created ourselves. In this post I’ll cover how to create one such file ourselves, and then finally what to do with it.

Before we go any further though, it must be noted, that for generating useful qch files, an appropriate documentation should already exist in one form or another. In this guide I’ll be presenting a method that uses source files with Doxygen documentation present in them, so let’s begin.

  1. Extract the source code containing Doxygen documentation into a folder
  2. Create a build folder inside it (or anywhere else where it is convenient)
  3. Open up your favourite CMake setup utility. Sometimes only the CMake GUI setup tool can do the trick even if everything is set correctly (otherwise you get errors like at the bottom of this post).
  4. Set the source and build path
  5. Add the CMAKE_DOXYGEN_GENERATE_QHP parameter and set its value to ON
  6. Set BUILD_DOCS to ON
  7. Make sure all the other build configuration parameters match your current installation (or you might not get all the docs)
  8. Run Configure then Generate in GUI, or run cmake . in command line (after you cd to the source folder)
  9. Go to build dir and run ‘make doxygen’
  10. Go to build/doc/doxygen/html folder
  11. Run qhelpgenerator index.qhp -o opencv.qch (don’t add any version number to the output name as it will complicate doc updates later)
  12. If you have some errors like ‘Error in line 19749: Opening and ending tag mismatch.’, open the generated .qhp file (it is an xml file) and comment out the offending line. It will be a </section> tag usually.
  13. If you see ‘Documentation successfully generated.’, move the generated .qch file to ~/.designer
  14. Start Qt Creator then go to Options->Help and switch to Documentation tab. Here add your qch file.
  15. Might need to restart Qt Creator and wait until it indexes the new documentation file.
  16. Switch to Help mode and try searching for some basic class or function. If documentation works, it will display results. From this point on the popup help in the source editor should also work.

That is all, enjoy a much more extended help system within Qt Creator.
One last thing: if the creators of the source don’t allow you to build code right into the source dir, the following error message might appear. In such cases just make sure to follow steps 2 to 4.

Bash

1
2
3
4
5
6
7

CMake Error at CMakeLists.txt:11 (message): 

  FATAL: In-source builds are not allowed.

         You should create a separate directory for build files.

-- Configuring incomplete, errors occurred!

As always, thanks for reading.