Development  »  Development Procedures  »  Integrating API documentation into Qt Creator Help

If you choose to use Qt Creator as your IDE, in combination with Ogre, you can import the API documentation into it. This way, you will be able to get context-sensitive help for all Ogre library functions by pressing F1. Just like with Qt library classes, a help tab will open with the relevant documentation.
This guide will guide you through the process of exporting the existing ogre documentation into a Qt help file.

doxygen

 
New versions of Doxygen come with the ability to export to QT help format. However, there is a bug in a lot of recent doxygen versions that cripples this feature (when pressing F1 on a function the help tab will show the top of the page, instead of scrolling down to the correct funtion). Up to the moment of this writing, even the latest version of doxygen (1.7.1) has this bug. Yet, the latest SVN version fixes this bug. For more information on this, see: Doxygen bug report

 

So our first move would be compiling and installing doxygen from SVN.

svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn
cd doxygen-svn/
./configure
make
make install

Setting up the doxyfile

Now that we have a good doxygen version, we have to recompile the Ogre documentation, but before we do that, we have to change the build config.
In a folder where you have the ogre source, say in ogre_src_v1-7-1/, modify the doxygen config file:

ogre_src_v1-7-1/Docs/src/html/html.cfg

 
At the bottom of the file, we will add some extra options:

#---------------------------------------------------------------------------
# Generate help files for Qt Creator
#---------------------------------------------------------------------------
GENERATE_QHP           = YES
QCH_FILE               = "../qthelp/ogre3d.qch"
QHP_NAMESPACE          = "Ogre"
QHP_VIRTUAL_FOLDER     = "ogre3d-1.7.1"
QHG_LOCATION           =  "/usr/bin/qhelpgenerator"

To be able to use qhelpgenerator, you need to have Qt installed. You also might need to change the location of the qhelpgenerator executable, depending on your configuration. Windows users would probably have to enter something like

#---------------------------------------------------------------------------
# Generate help files for Qt Creator
#---------------------------------------------------------------------------
GENERATE_QHP           = YES
QCH_FILE               = "../qthelp/ogre3d.qch"
QHP_NAMESPACE          = "Ogre"
QHP_VIRTUAL_FOLDER     = "ogre3d-1.7.1"
QHG_LOCATION           =  "C:/Qt/bin/qhelpgenerator.exe"

Running doxygen

At this point, doxygen should be properly configured for generating our Qt help file from the HTML that doxygen creates.
Now, for recompiling the docs, go to the folder Docs/src/ and issue the command

doxygen html.cfg

 
After the compiling is done, the generated Qt help file will be in

ogre_src_v1-7-1/Docs/api/qthelp/ogre3d.qch

Importing the help file in Qt Creator

We're almost there! The only thing we have to do now is load the ogre3d.qch file into Qt Creator. Start Qt creator and go to Tools > Options, open up Help and Documentation. Click Add and browse for the qch file that was just created, then Apply. I usually need to have some patience before the documentation starts working. It's best to close Qt creator at this point, and restart it.

Try it, open up some code that uses Ogre3D classes in the editor, move your mouse over one of their methods and press F1.