I have made some progress on this:
=== Making Doxygen documentation look like Qt documentation ===
For anyone interested, I’ve attached a zip file that includes files that produce Doxygen documentation which mimics the look of Qt documentation fairly closely. The files in the Doxygen folder need not change from one project to another. Many options in the doxygen.in file should stay as they are to produce Qt-like documentation, but a few would need to be customized for each project. The ShellModel.qch file is a work-in-progress example of documentation generated with these files.
Known problems and things to be done:
1. The HTML version looks good in Firefox and Opera, but Internet Explorer 7 doesn’t honor the CSS I used to get the prototype statement
in the detailed descriptions all on one line, instead of in a table with each parameter on a separate line... in fact, all the prototype lines in detailed descriptions look awful in IE 7. I suspect there is no way to get IE’s rendering of Doxygen documentation as close to Qt documentation as I’ve done for the other browsers, but I’m sure some CSS hack or other could make it more presentable than it is now.
2. I see no way to trick Doxygen into understanding the \value tag used in the Qt source for listing enum values. The workaround I have now is to code an HTML <table>; I’ve included CSS that applies to tables in the documentation to make them appear the way enum value tables look in Qt documentation.
3. I don’t know if the Contents pane entries can be modified; I really haven’t been too concerned with them, though they are a bit different than in Qt documentation. Similarly, the “Class List” and “Class Members” pages don’t quite match Qt style. I actually like having the class list contain the brief descriptions of the classes, since most projects will have far fewer classes to document than Qt, so the additional space used per class shouldn’t be a problem. The alphabetic index on class members pages is currently suppressed by the CSS; I’m not yet sure whether that can be fixed without showing something else that “looks the same” to CSS, but isn’t wanted.
4. I haven’t tested everything under the sun. In particular, it looks like there might be special CSS in Doxygen for templates, and I haven’t tried documenting any templates yet. I haven’t yet customized the main page or tried adding supplemental pages.
=== Making Doxygen documentation link to Qt documentation
I found the answer to this problem in a blog post. The steps are:
1. Grab a KDE API documentation tarball and extract the qt.tag file from the qt sub-folder. (That link is failing right now, but I presume it’s just temporary. I presume there is a way to produce this file from Qt source — KDE must have done it somehow — but I don’t know the steps.)
2. In the Doxygen configuration file, include:
TAGFILES = C:\INTERNAL\Qt\Doxygen\qt.tag=qthelp://com.trolltech.qt/qdoc/
TAGFILES = C:\INTERNAL\Qt\Doxygen\qt.tag=qthelp://com.trolltech.qt/qdoc/
To copy to clipboard, switch view to plain text mode
replacing C:\INTERNAL\Qt\Doxygen\qt.tag with the path to the extracted qt.tag file.
3. Unfortunately, a few things don’t link as they should — for example, I couldn’t get enums, like Qt::ItemDataRole, to work. The solution I found was to include this in the configuration file:
ALIASES = "qt{2} = <A HREF=\"qthelp://com.trolltech.qt/qdoc//\1\">\2</A>"
ALIASES = "qt{2} = <A HREF=\"qthelp://com.trolltech.qt/qdoc//\1\">\2</A>"
To copy to clipboard, switch view to plain text mode
and then use code like
\sa \qt{qt.html#ItemDataRole-enum,Qt::ItemDataRole} enumeration
\sa \qt{qt.html#ItemDataRole-enum,Qt::ItemDataRole} enumeration
To copy to clipboard, switch view to plain text mode
to make the link. To find the correct link target, find what you want to link on the web and use only the filename and anchor portion.
4. The above is for Qt documentation in *.qch form. To generate HTML pages that link to the web documentation, replace qthelp://com.trolltech.qt/qdoc/ with http://doc.qt.nokia.com/latest/ in both configuration lines. (By defining the qt{2} alias as suggested above, only the configuration file has to change, not the source documentation.)
=== Adding a documentation build ===
Here I’m completely stuck. Sx Degrees’ point strikes me as a good one — so I’m thinking that rather than add Doxygen as an extra build step, what I want is to add “Document” as an alternative to “Debug” and “Release.” The same reference that showed me how to link into Qt documentation has an example of a CMakeLists.txt file with a Doxygen step and a model configuration file, but I am getting nowhere trying to find documentation on how to translate that to QMake.
After creating a new build configuration called Document, I gather I need to change the -spec argument to qmake.exe to something that will instruct it how to generate a Doxygen configuration file with appropriate substitutions for directories, files and so on, then either build a makefile that will run Doxygen, or just run Doxygen itself... but I can’t find any documentation on how to do that, and the workings of the *.conf files in Qt\mkspecs are not at all clear to me. I don’t know how QMake determines what to do.
Then I’d hope there is some way to make a new version of the standard App project that would generate a project including the new Document build configuration along with Debug and Release?
Any pointers on where to look for instruction? examples? anything?
Bookmarks