Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2011-10-04 20:59:40

On 03/10/11 04:15, Edward Diener wrote:
> On 10/2/2011 6:03 PM, Dave Abrahams wrote:
>>
>> on Thu Sep 29 2011, Mateusz Loskot<mateusz-AT-loskot.net>  wrote:
>>
>>> On 28/09/11 17:09, John Maddock wrote:
>>>>>> Perhaps quickbook to reStructuredText is a feasible solution.
>>>
>>>>>> Then all move to writing in reStructuredText, etc.
>>>>>
>>>>> But then there's the issue of lossiness.
>>>>
>>>> And lets not forget that some of us really like quickbook ;-)
>>>
>>> I do like quickbook too.
>>> Although may intention was to discuss the workflow of documenting Boost,
>>> I think I have identified what is the biggest pain to me: Doxygen
>>> integration in BoostBook.
>>>
>>> Doxygen is widely used C++ code documenting tool.
>>> Fortunately or unfortunately, it is also used by many Boost authors.
>>>
>>> Doxygen does not support many of the terms/concepts/elements used across
>>> Boost libraries. It is also becasue it is almost impossible to document
>>> them well at source code levels.
>>> However, things like "concept and model" exist at source code level,
>>    do not?---------------------------------^
> 
> Doxygen generally deals with C++ constructs, and there is no C++
> construct called "concept" or "model". If concepts had been voted into
> C++0x, then no doubt doxygen would have considered documenting it as a
> C++ construct.
> 
> Conversely there is no limit in doxygen to documenting whatever you want
> as free-from doxygen documentation and so you could document 'concepts'
> in doxygen if you wanted to do so in whatever format you like. There are
> a number of techniques for this but probably the easiest is to just add
> such documentation to a @file documentation, and it will show up in the
> final output.

Documenting concepts in Doxygen is certainly possible, however such
content would need to be processed to classify it as a concept.

I'd rather consider documenting concepts externally to source code (in
BoostBook or QuickBook) and then process it to combine with Doxygen XML
output, link template parameters with type requirements, link to
corresponding models, etc.

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