Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2011-10-06 20:22:55

On 06/10/11 07:24, Paul A. Bristow wrote:
> Dave Abrahams wrote:
>> 
>> I'm not so sure.  The universe of design options is so vast that I
>> think users need to be presented with alternatives.  I find
>> http://cpp-next.com far easier to read than most of the Boost
>> pages, for example.
> 
> I like that too, but I fear we are not discussing the most important
> thing.
> 
> This is focussing on style : I'm worrying about *detailed content* -
> and what is I believe is often missing from many Boost docs.
> 
> For me, the really important issue problem is how and where to
> document what class, functions, etc do, pre and post conditions,
> 'concepts' and results, returns and side effects, and what it does
> if you provide bad input - throw or error code or?.

This fits to my idea of well-designed conventions of documenting Boost.
One of the fundamental convention that is needed, IMHO, is the structure
of content.
In documentation of every library in Boost, similar concepts can be
identified, so abstraction of those is possible. Thus, it is possible to
set a common framework for all libraries.
Writing documentation could be simpler if authors are given
such framework and are asked to fill the gaps (overview, tutorial,
design, reference (concepts, models, algorithms, etc.)  with content.

All libraries should use table of contents with similar layout and content.

This will make the documentation easily discoverable.

> So we have two choices.
> 
> You provide separate text, perhaps in text and/or tables, separately.
> But for any non-trivial library, you need a tool to organise this,
> and this means some 'mark-up' system.  And keeping the docs in step
> with the code is more difficult.
> 
> Or you put the documentation in with the C++ code as comments with
> some 'mark-up'.  This is all the Doxygen conventions do - and they
> could be processes by other tools too, best of all by an add-in to 
> the compiler.  This clutters the code, but syntax color makes this a
> non-problem for me.  (You are reading this in color and not B&W ;-)

Isn't it possible to allow both and combination?
If we translate Doxygen to BoostBook, then everything is BoostBook.
The next step is to generate output with necessary structure.

Best regards,

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