Re: [Boost-docs] Sphinx integration

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

On 10/3/2011 10:04 AM, Dave Abrahams wrote:
>
> 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?

I agree with you. There is no big advantage trying to fit into doxygen, 
which is largely an attempt to document at the source code level C++ 
constructs, documentation that is outside the area of a C++ construct 
when one has quickbook to do that.