[Boost-docs] Translating Doxygen defgroup to Quickbook

Subject: [Boost-docs] Translating Doxygen defgroup to Quickbook
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2010-02-28 16:51:13

Hi,

Doxygen supports @defgroup command [1] that can be used to make
a group of related elements. While combining Doxygen-generated XML
with Quickbook, I've noticed that this information is dropped - no
pages or sections are generated for defgroup.

I found that the libraries seem to handle the defgroup thing on their
own, in a custom way. It suggests there is no support for it in
Quickbook. So, I investigated Boost Asio docs in details as it looks
to me as best example of such solution.

What Boost.Asio does is
- generate the Doxygen-encoded docs to XML output
- transform the XML to Quickbook file reference.qbk [2]
using the xsltproc tool and custom stylesheet reference.xsl [3]
The whole process is fired with a simple script [4]

For example, header /boost/asio/read.hpp defines "async_read" group [5]
that gathers all overloads of the async_read function.
The documentation generator explained above puts all async_read versions
under common node [6] in HTML output from Quickbook.

The Boost Asio manner of handling with the defgroup thing
sounds very well.

However, before I'll adopt it for Boost Geometry, I'd like to know if
there is any better or let's say recommended way to achieve this.
Perhaps Quickbook has got native support of Doxygen defgroup, etc.

I'd be thankful for comments.

[1]http://www.stack.nl/~dimitri/doxygen/grouping.html
[2]https://svn.boost.org/trac/boost/browser/trunk/libs/asio/doc/reference.qbk
[3]https://svn.boost.org/trac/boost/browser/trunk/libs/asio/doc/reference.xsl
[4]https://svn.boost.org/trac/boost/browser/trunk/libs/asio/doc/doxy2qbk.pl
[5]https://svn.boost.org/trac/boost/browser/trunk/boost/asio/read.hpp?rev=58761#L31
[6]http://www.boost.org/doc/libs/1_42_0/doc/html/boost_asio/reference/async_read.html

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org