Some Lesser Known Qt Tools and Commands

Some Lesser Known Qt Tools and Commands - Part 3

By Jeff Tranter


In this next installment of our blog series on lesser-known Qt commands, we'll look at four tools related to documentation: qdoc, qhelpgenerator, qcollectiongenerator and qhelpconverter.

Qdoc

Qdoc1 is the tool used to generate the developer documentation for the Qt Project. It is not specific to Qt, and can be used to create documentation for other projects or applications.

Similar to tools like Javadoc2 and Doxygen3, it works by extracting structured comments from source files and using them to generate documentation in HTML or other formats.

The comments are typically located in cpp, qml or qdoc files and use a simple markup language with tags. A partial example from the Qt source file for the QBrush class, qbrush.cpp, is shown below:

/*!
\class QBrush
\ingroup painting
\ingroup shared
\inmodule QtGui
\brief The QBrush class defines the fill pattern of shapes drawn
by QPainter.
A brush has a style, a color, a gradient and a texture.
The brush style() defines the fill pattern using the
Qt::BrushStyle enum. The default brush style is Qt::NoBrush
(depending on how you construct a brush). This style tells the
painter to not fill shapes. The standard style for filling is
Qt::SolidPattern. The style can be set when the brush is created
using the appropriate constructor, and in addition the setStyle()
function provides means for altering the style once the brush is
constructed.
...
*/

The qdoc program is a command line utility which accepts a number of options, all of which are well documented.

Something to note is that, beginning with Qt 5.5, a new way to run qdoc is available that can, in some cases, greatly reduce the time taken to generate Qt 5 documentation. Read the documentation about the new "single execution mode" for more details.

Qhelpgenerator

Qt help can be produced as separate HTML files, but it is often desirable to store the documentation in a smaller self-contained format. The qhelpgenerator tool is used to do this. It accepts a Qt Help Project (qhp) file that defines the structure of the documentation and html files and produces a standalone qch or Qt Compressed Help file containing all the documentation.

Qcollectiongenerator

Help can also be combined into collections of help files. A help collection can include any number of compressed help files.

The qcollectiongenerator tool is used for generating a qhc or Qt Help Collection file. It accepts as input a Qt Help Collection Project (qhcp) file, which defines the compressed help files that should be included in the collection. The tool produces a Qt Help Collection (qhc) file that contains references to the compressed help files in the collection.

Qhelpconverter

The last documentation-related tool we will look at is qhelpconverter.

In Qt versions up to 4.3, the help system was based on the Document Content File (DCF) and Qt Assistant Documentation Profile (ADP) file formats. Qt 4.4 and later (including Qt 5) use different file formats. In order to provide a way to migrate existing files to the newer format, the qhelpconverter tool is provided. It is a graphical wizard-type application that steps the user through the process of converting help files to the new qch and qhcp formats. Screen shots of a couple of the wizard screens are shown below:

Qt Wizard

Qt Wizard

Summary

This blog post was not intended to be a tutorial for the documentation system. All of these different help-related files and tools may sound confusing, but the Qt documentation4 does a good job of explaining the overall process and I refer you to it for more details.

References

  1. QDoc Manual, Qt documentation web site, accessed 1 Jun 2015, http://doc.qt.io/qt-5/qdoc-index.html
  2. Javadoc tool, Java SE documentation web site, accessed 1 Jun 2015, http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/
  3. Doxygen tool, project web site, accessed 1 Jun 2015, http://www.doxygen.org
  4. The Qt Help Framework, Qt documentation web site, accessed 1 Jun 2015, http://doc.qt.io/qt-5/qthelp-framework.html