History: Integrating API documentation into Qt Creator Help

            If you choose to use [http://qt.nokia.com/products/developer-tools/|Qt Creator] as your {LEX()}IDE{LEX}, 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.

{maketoc}

!doxygen

New versions of [www.doxygen.org/|Doxygen] come with the ability to export to QT help format. However, there was a bug in doxygen versions 1.7.1 and below 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). So make sure to install at least doxygen version 1.7.2.

!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:
{CODE()}ogre_src_v1-7-1/Docs/src/html.cfg{CODE}

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

{CODE(caption="Lines to add to html.cfg in linux")}
#---------------------------------------------------------------------------
# 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"
{CODE}
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 
{CODE(caption="html.cfg adaption for windows")}
#---------------------------------------------------------------------------
# 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"
{CODE}


!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/ and issue the command
{CODE(caption="command for starting doxygen")}
    doxygen src/html.cfg
{CODE}

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

{CODE()}ogre_src_v1-7-1/Docs/api/qthelp/ogre3d.qch{CODE}

~tc~I did not find out how to create the Qt help file with the Cmake buildscript, so using make doc will not work. I'm not that familiar with Cmake, so maybe someone else might know an easy way to fix this.~/tc~

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