Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Edward Diener (eldiener_at_[hidden])
Date: 2011-10-03 03:15:03

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.