Friday June 20, 2008 by sping | Comments
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.
You can grab the current code from our Subversion repository like this:
$ svn co svn://labs.trolltech.com/svn/documentation/doxygen2qthelp
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.
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.
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.
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.
$ 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
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.
## Paths Relative to the 'html' folder!
GENERATE_HTMLHELP = YES
DOXYGEN2QTHELP_LOCATION = doxygen2qthelp
QTHELP_CONFIG = ../qwt.ini
QTHELP_FILE = ../qwt-5.0.2-doc.qch
That's it - a single call to Doxygen can now produce .qch files.
Please report any bugs you might find through the Trolltech Bug tracker. Feedback is also welcome. Thank you!
Download the latest release here: www.qt.io/download.
Qt 6 was created to be the productivity platform for the future, with next-gen 2D & 3D UX and limitless scalability.
Find webinars, use cases, tutorials, videos & more at resources.qt.io
Check out all our open positions here and follow us on Instagram to see what it's like to be #QtPeople.
Näytä tämä julkaisu Instagramissa.Henkilön Qt (@theqtcompany) jakama julkaisu