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:
$ svn co svn://labs.trolltech.com/svn/documentation/doxygen2qthelp
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.
- 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.
- Run Doxygen
If everything went smoothly we should have both HTML documentation and the index.hh* in doc/html/ . - 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
- 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.
- Apply the patch and rebuild Doxygen
- Add a few lines to the Doxyfile:
## Paths Relative to the 'html' folder!
GENERATE_HTMLHELP = YES
DOXYGEN2QTHELP_LOCATION = doxygen2qthelp
QTHELP_CONFIG = ../qwt.ini
QTHELP_FILE = ../qwt-5.0.2-doc.qch - 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!
No related posts.
5 comments
Wonderful
… We needed something like that for GCF and we wrote our own little converter at that time. It is interesting to note that in future Doxygen will officially support it. BTW, in doxygen2qthelp is there a mechanism for us to merge our own set of table of contents with whats generated by doxygen2qthelp? Because that would be great!..
I’ve just ran this script on a bunch of the apidocs in kdelibs — the indexing is a bit off, and the header renders weird, but it makes life _so_ much easier, not having to go through TechBase every time to get the API documentation!
And having it side-by-side with the Qt documentation makes KDE programming that much easier. This will definitely make the barrier to entry into KDE _much_ easier (just as having assistant made the learning curve for Qt quite pleasant, as well).
Once again you prove that if one just procrastinates long enough somebody else (here: you) will do the work. I love Assistant for two main reasons: It separates help pages from other web pages (more order) and the search is just great.
Nice Tool! Will this work on any index.hh* files or is your tool dependent on the doxygen output?
Because I am looking for a way to get DocBook Documents into QtAssitant and DocBook supports *.chm as a target as well,
so your tool might work to convert DocBook to Qt Help as well, right?
Will this work only on Doxygen output, or can it be applied to any tool that generates Microsoft Help Files? I would like to convert DocBook documents to Assistant files and DocBook XSL can output Microsoft Help Files.
Will it be possible to run your tool on the output of DocBook XSL instead of the doxygen output?
Comments on this entry are closed.