Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2011-10-04 21:16:15

On 04/10/11 18:16, Dave Abrahams wrote:
> on Mon Oct 03 2011, "Paul A. Bristow" <pbristow-AT-hetp.u-net.com> wrote:
> 
>> Using Doxygen properly and fully, I feel that Boost documentation
>> could be much improved.
>>
>> What is wrong is the common delusion that you just chuck your C++ code
>> into Doxygen it magically does the whole job : it doesn't - it is a
>> tool for *helping you to document your source code*.
>>
>> You have to do the work - and experience has shown that it is much
>> easier done when you first write
>> the code!
> 
> If that is indeed the case, Paul, someone (I'm lookin' at you) needs to
> write a guide to using Doxygen for Boost.  I would definitely try to use
> it next time if someone could show me how to make it really work for our
> docs.

Paul listed very useful features and directives of Doxygen, but without
explanation how to use them to write rockstar documentation for Boost.

Doxygen has a feature which may be considered as weakness for Boost,
it is how Doxygen structures documentation, at least, the HTML pages.
I think Doygen can deliver content (the XML output) and it needs to be
processed and combined into structure required  (and defined) by Boost
authors.

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