Doxygen and Qt... is there a FAQ?

[wysota]

I presume the right way to generate Qt-like documentation is to use Doxygen? At least, the documentation comments in Qt source files sure look like Doxygen documentation, and Doxygen can generate *.qch files if you tell it where to find qhelpgenerator.exe.

There is no single "right way". Doxygen was created to mimic Trolltech's internal documenting tool and it's the suggested tool to be used for generating documentation. But certainly not the only one.

Assuming Doxygen is the way to go, are there style sheet and layout files to be found that generate documentation which roughly matches the look of the built-in Qt documentation?

None that I know of. I have a XSL template which makes it possible to convert xml output from doxygen to something that looks similar to official Qt docs but as I don't use doxygen anymore, the stylesheet is not maintained.

It would appear that I should be able to link transparently to the built-in Qt documentation, but I can’t figure out what I have to do to make that work.

I'm not sure if linking to the official docs is possible using doxygen as doxygen uses a different name mangling scheme than the official docs. In theory you would do it using a tag file created i.e. using ctags.

Assuming I get all that working... is there a straightforward way to add a Doxygen step to the build process, so that generating updated documentation becomes automatic whenever I rebuild?

Yes, that's more or less doable. Either use QMAKE_EXTRA_TARGETS or QMAKE_POSTTARGET_DEPS or something like that.

[Lykurg]

None that I know of. I have a XSL template which makes it possible to convert xml output from doxygen to something that looks similar to official Qt docs but as I don't use doxygen anymore, the stylesheet is not maintained.

Sounds good! I always wanted to do one, but never did. Can you share your template? That would be great!

[wysota]

Sounds good! I always wanted to do one, but never did. Can you share your template? That would be great!

I'll have to look for it. But it's far from being perfect, I stopped using it long ago.

[3DH]

Hi,

many Thanks for your Qt-style layout! It's great!

I use it to embed my own doxygen docu directly into the QtCreator by adding these lines to the doxygen config:


#---------------------------------------------------------------------------
# configuration options for QtHelp output
#---------------------------------------------------------------------------
GENERATE_QHP = YES
QHP_NAMESPACE = doc.mycompany.com
QHP_VIRTUAL_FOLDER = doc
QHG_LOCATION = qhelpgenerator


You need Doxygen 1.70 or higher and the Qt Toolkit 4.6 or higher to create the QtHelp-Files (.qch).

This config creates a directory /qhc/ with a file named <PROJECTNAME>-<PROJECTVERSION>.qhc

To enable it in QtCreator open it, goto "Extras -> Settings -> Help -> Documentation" and add the file.

Then restart QtCreator and you can use your own docu by pressing F1

ciao,
Chris