Re: Sphinx integration

on Sun Oct 02 2011, Edward Diener <eldiener-AT-tropicsoft.com> 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". 

Yes I know.  I was suggesting that Mateusz left out a couple of words
above.  Otherwise it seems not to gibe with reality.

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

But what's the advantage in that over, say, just using quickbook,
boostbook, or any of the other non-automatic tools for that part of the
documentation?

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com