Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-10-11 16:19:05

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Mateusz Loskot
> Sent: Tuesday, October 11, 2011 4:04 PM
> To: Dave Abrahams
> Cc: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] Sphinx integration
> 
> On 11/10/11 15:55, Dave Abrahams wrote:
> > on Tue Oct 11 2011, Mateusz Loskot<mateusz-AT-loskot.net>  wrote:
> >> On 11/10/11 14:40, Dave Abrahams wrote:
> >>> on Tue Oct 11 2011, Mateusz Loskot<mateusz-AT-loskot.net>   wrote:
> >>>
> >>>>> 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.
> >>>
> >>> +1
> >>>
> >>> In fact, it shouldn't be up to the individual libraries; the
> >>> transformation should be part of the documentation build process.
> >>
> >> Yes, that's what I have in mind.
> >>
> >> Now, regarding the implementation of such translator:
> >> - is there anything already available in current doc tools in Boost,
> >> Vault,...?
> >> - if not, where it should go? separate cmd line tool like quickbook?
> >> - what's best way to parse XML for BoostDoc for ? libxml, Boost.Tree,
> >> Spirit?
> >
> > I don't think I know the answers oto these questions.  There's
> > *something* in Boost.Build for this, but that's as much as I remember.
> 
> OK. I'll try to discover it myself.
> Thank you, Paul and others for brainstorming the whole thing.

I think you will find that the jamfiles for lots of recent libraries will give some clues on how
most people are doing it.

Paul

PS But my message that the *content* of the comments that document what parameters are, what
functions and classes do, and what the results or returns are is the really important thing that IMO
needs improving.  Doxygen comments and the current methods of processing of them is one way of
achieving it.