History: Integrating API documentation into Qt Creator Help

• «
• »

            If you choose to use [http://qt.nokia.com/products/developer-tools/|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.

{maketoc}

!doxygen

New versions of [www.doxygen.org/|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. (more info, see: https://bugzilla.gnome.org/show_bug.cgi?id=623673)
~tc~Starting from doxygen 1.7.2 (or whatever the next release will be), we can probably let the users just download and install that release version~/tc~

So our first move would be compiling and installing doxygen from SVN.
    {CODE(caption="linux commands for installing doxygen from svn")}svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn
cd doxygen-svn/
./configure
make
make install{CODE}
~tc~Needs windows alternative~/tc~

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