Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2011-10-11 12:40:35

On 09/10/11 02:23, Dave Abrahams wrote:
> on Fri Oct 07 2011, Mateusz Loskot<mateusz-AT-loskot.net>  wrote:
>> On 07/10/11 21:04, Dave Abrahams wrote:
>>> on Fri Oct 07 2011, Mateusz Loskot<mateusz-AT-loskot.net>  wrote:
>>
>>>> Looking at slides 30-37, I'm wondering...why Boost documentation
>>>> looks and feels more like a scientific paper than a handbook.
>>>> The handbooks are for mortals. The scientific paper are not.
>>>> The Boost is developed by immortals, so let them use scientific paper.
>>>> The Boost is for use mostly by mortals who need handbook, but not
>>>> scientific paper, about Boost.
>>>>
>>>> If Boost documentation (and website) aims the slides 30-37, it will be
>>>> a rockstar documentation.
>>>>
>>>> Is it possible at all?
>>>
>>> Yes, it's possible.  Are you familiar with
>>> https://svn.boost.org/trac/boost/wiki/ImprovingBoostDocs#Objectives?
>>> That could be revived.  Matias Capeletto was the driving force, IIRC.
>>
>> I found it long time ago, forgot and haven't come back since.
>>
>> The objectives are aligned to what we've discussed so far.
>> The idea is feels big. I think it would improve a lot if
>> we could implement the unification for use and processing
>> of Doxygen in Boost.
>
> Sorry, I don't know what you mean by "implement the unification for use
> and processing of Doxygen in Boost."  Could you explain?

I mean that, presumably, it is a good idea if all Boost libraries
documented using Doxygen use exactly the same tool to transform the 
Doxygen comments into API reference in BoostBook or QuickBook format.

This way, look & feel of all API references would be consistent
and authors would probably be encouraged to update comments for better 
Boost API documentation coverage.

Makes sense?

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