Intro

Hello! I have something to show you. I’ve been working on a tool that teams up with Doxygen to produce .qch files (Qt Compressed Help) for use with Qt Assistant from your code documentation - a feature that has been asked for repeatedly since 2003 ([1][2][3]..). In this post I will introduce doxygen2qthelp, the answer to your request.

Download

You can grab the current code from our Subversion repository like this:

Building

I should mention doxygen2qthelp requires a Qt version later than 4.4.0, which at the moment means a snapshot of 2008-04-24 or later. If you start building now be sure to configure with -assistant-webkit. More about this later.

Background

Doxygen has been able to produce .chm files (Compressed HTML) from properly documented code. To be precise Doxygen does not create the .chm files itself: instead it produces a bunch of files that are used to instruct the Microsoft® HTML Help Compiler (hhc.exe). These three files contain the table of contens (file index.hhc), the list of keywords appearing in the index (file index.hhk), and a project description (file index.hhp). The former two of these are written in some form of "perverted HTML". What doxygen2qthelp does: take these files, parse through the soup, and create a ready-to-go .qch file for viewing in Qt Assistant. Alternatively, a fine-control .qhp file (Qt Help Project) can be produced.

Usage

Let’s say you were the author of the QWT library and you felt like shipping .qch files of your documentation. What would you do? Let’s first look at a manual approach, and see what we can automate after.

1. Enable Microsoft® HTML Help output
   First you need to tell Doxygen to generate HTML Help output. To do that you enable GENERATE_HTMLHELP
   
   

   GENERATE_HTMLHELP = YES
   

   in the Doxyfile. Without HHC_LOCATION being set Doxygen will just produced the index.hh* files and not try to call the Help Compiler from Microsoft®. That’s just how we like it, especially on our Linux Machine.

2. Run Doxygen
   If everything went smoothly we should have both HTML documentation and the index.hh* in doc/html/ .
3. Run doxygen2qthelp
   Now doxygen2qthelp comes into play. Invoke it from the QWT source folder like this:
   
   

   $ doxygen2qthelp --namespace=net.sourceforge.qwt --folder=qwt-5.0.2 doc/html/index.hhp qwt-5.0.2-doc.qch
   

   Alternatively you could also write this calls information into an .ini file and invoke it like this:

   
   $ doxygen2qthelp --config qwt.ini

   -- qwt.ini --
Namespace = net.sourceforge.qwt
VirtualFolder = qwt-5.0.2
InputFilename = doc/html/index.hhp
OutputFilename = qwt-5.0.2-doc.qch


4. Enjoy
   Open the documentation in Qt Assistant, preferrably a version from Qt 4.4.0 or later configured to use Webkit in Assistant (./configure -assistant-webkit). Without Webkit parts of the Doxygen HTML will look quite messy.

Automation

Wouldn’t it be cool if we could teach Doxygen to call doxygen2qthelp for us? Good news: I wrote a patch against Doxygen 1.5.6 for you (see doxygen_patch folder). Dimitri van Heesch and I planned to integrate that patch upstream for one of the next Doxygen releases.

1. Apply the patch and rebuild Doxygen
2. Add a few lines to the Doxyfile:
   
   

   1. 1. Paths Relative to the 'html' folder!
         

   GENERATE_HTMLHELP = YES
   DOXYGEN2QTHELP_LOCATION = doxygen2qthelp
   QTHELP_CONFIG = ../qwt.ini
   

   QTHELP_FILE = ../qwt-5.0.2-doc.qch
3. Run Doxygen

That’s it - a single call to Doxygen can now produce .qch files.

Final words

Please report any bugs you might find through the Trolltech Bug tracker. Feedback is also welcome. Thank you!

So the time is finally here. Qt 4.4.0 was released a few weeks ago and as promised Qt Jambi is right behind. A lot of effort has gone into this one, in addition to supporting all the new Qt features, like Phonon, Webkit, Widgets in Graphics View, XQuery and Qt Concurrent, we also have a seriously improved deployment system, JDBC support and a compile-time checked signal-slot approach for the paranoid. Its a good time to be a Java developer I tell yah! We already mentioned all the featuers in the Qt Jambi 4.4.0 Preview Blog so we won’t repeat ourselves here… (There is a danger in linking to eskils blog, as it links to others again, which again links to others, which in the end proves to be a fairly complex graph, but then again… we are engineers and like that kind of stuff)

Under the cover we’ve also done quite some work. We also did an overhaul of the garbage collection and memory management subsystem and hopefully ironed out all the bumps and dents. We’ve also done some work on the build system, so that our users that build from source have a bit more substantial buildsystem to work with. Previously it was a complex install document, which has been replaced by a simple ant command which just does it all… I was very happy to see that the deployment system & ANT build scripts works well enough for the webstart to look like a plain, normal webstart app:

No magic nativejar or anything like that, just the qtjambi-win32-msvc2005-4.4.0_01.jar in the classpath and that is enough to load it, jpeg and svg plugins and all. The good thing is that the files included in the webstart are produced directly by the ant script with all dependencies etc set up properly… (well… almost properly, it took us an evening last week to get it really working, but now it works properly). Because of the fixes to memory management and deployment Eskil and I got these offical diplomas:

So, what more is there to say… Try the webstart with its new demos, download the packages and start hacking!

-
The Qt Jambi Team