Results 1 to 7 of 7

Thread: Doxygen and Qt... is there a FAQ?

  1. #1
    Join Date
    Nov 2009
    Posts
    129
    Thanks
    4
    Thanked 29 Times in 29 Posts
    Qt products
    Qt4
    Platforms
    Windows

    Default Doxygen and Qt... is there a FAQ?

    As part of a larger project, I’m building a class that is likely to be useful in various Qt projects. So, of course, I’d like to generate Qt-like documentation that will be comfortably accessible in the Help mode of QtCreator. It seems like the answers to these questions should be in a FAQ somewhere, but if they are, I can’t find it.

    • 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.

    • 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? I’m not necessarily looking for something indistinguishable from Qt documentation, but the default look of Doxygen documentation is jarring when viewed next to the standard documentation in Qt Creator.

    • 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. For example, if a parameter to one of my functions is a QString, the word QString in the function definition should link to the Qt documentation page for QString, just as it would in built-in Qt documentation. What little bit of magic must I code to make that happen?

    • 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?

  2. #2
    Join Date
    Jan 2006
    Location
    Warsaw, Poland
    Posts
    33,359
    Thanks
    3
    Thanked 5,015 Times in 4,792 Posts
    Qt products
    Qt3 Qt4 Qt5 Qt/Embedded
    Platforms
    Unix/X11 Windows Android Maemo/MeeGo
    Wiki edits
    10

    Default Re: Doxygen and Qt... is there a FAQ?

    Quote Originally Posted by Coises View Post
    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.
    Your biological and technological distinctiveness will be added to our own. Resistance is futile.

    Please ask Qt related questions on the forum and not using private messages or visitor messages.


  3. #3
    Join Date
    Apr 2010
    Posts
    769
    Thanks
    1
    Thanked 94 Times in 86 Posts
    Qt products
    Qt3 Qt4
    Platforms
    Unix/X11

    Default Re: Doxygen and Qt... is there a FAQ?

    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. For example, if a parameter to one of my functions is a QString, the word QString in the function definition should link to the Qt documentation page for QString, just as it would in built-in Qt documentation. What little bit of magic must I code to make that happen?
    See the Doxygen Doxytag documentation.

    As for generating new documentation on each rebuild - I'd recommend some other approach. That could trigger an awful lot of Doxygen runs during development.

    We wrote a small script that ran under cron every night. It checked out our source repository, ran Doxygen on it and uploaded the new documentation to the webserver. By the time everyone arrived in the morning, they had a fresh batch of documentation.

    For stylesheets - visit any Qt documentation page, select "View source" in your browser, and search for "css" The file "classic.css" seems to be the favorite - you can view it directly here. This ought to get you most of the way there; although Doxygen may not output exactly the same chunks or use exactly the same names, it'll probably recognize enough that the colors, fonts and overall "look" will be very similar.

  4. #4
    Join Date
    Jan 2006
    Location
    Germany
    Posts
    4,380
    Thanks
    19
    Thanked 1,005 Times in 913 Posts
    Qt products
    Qt4
    Platforms
    Unix/X11 Windows Symbian S60
    Wiki edits
    5

    Default Re: Doxygen and Qt... is there a FAQ?

    Quote Originally Posted by wysota View Post
    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!

  5. #5
    Join Date
    Nov 2009
    Posts
    129
    Thanks
    4
    Thanked 29 Times in 29 Posts
    Qt products
    Qt4
    Platforms
    Windows

    Default Some progress

    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:
    Qt Code:
    1. 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:
    Qt Code:
    1. 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
    Qt Code:
    1. \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?
    Attached Files Attached Files

  6. The following user says thank you to Coises for this useful post:

    seanfisk (9th March 2011)

  7. #6
    Join Date
    Jan 2006
    Location
    Warsaw, Poland
    Posts
    33,359
    Thanks
    3
    Thanked 5,015 Times in 4,792 Posts
    Qt products
    Qt3 Qt4 Qt5 Qt/Embedded
    Platforms
    Unix/X11 Windows Android Maemo/MeeGo
    Wiki edits
    10

    Default Re: Doxygen and Qt... is there a FAQ?

    Quote Originally Posted by Lykurg View Post
    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.
    Your biological and technological distinctiveness will be added to our own. Resistance is futile.

    Please ask Qt related questions on the forum and not using private messages or visitor messages.


  8. #7
    Join Date
    Jun 2010
    Posts
    1
    Qt products
    Qt4
    Platforms
    Unix/X11 Windows

    Default Re: Doxygen and Qt... is there a FAQ?

    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

Similar Threads

  1. [Doxygen] EXTRACT_ALL and warnings
    By Boron in forum General Programming
    Replies: 0
    Last Post: 18th April 2009, 14:55
  2. DoxyGate - Doxygen GUI Frontend
    By doxygate in forum Qt-based Software
    Replies: 11
    Last Post: 12th January 2009, 17:48
  3. How to configure Doxygen in Fedora core 4
    By Manohar in forum General Programming
    Replies: 2
    Last Post: 22nd March 2008, 06:17
  4. Doxygen and Qt Classes
    By chaosgeorge in forum Qt Programming
    Replies: 6
    Last Post: 10th December 2006, 01:38
  5. doxygen config like qt docs
    By danadam in forum General Discussion
    Replies: 1
    Last Post: 3rd September 2006, 19:10

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •  
Digia, Qt and their respective logos are trademarks of Digia Plc in Finland and/or other countries worldwide.