Re: [boost] Documentation Redux (was Re: Boost 1.36.0 releasenotice)

From: John Maddock (john_at_[hidden])
Date: 2008-08-18 08:39:49

Daniel Wallin wrote:
>>> Quickbook is also a nice documentation language to use, but the
>>> reliance on Boostbook+XSLT makes it harder to pull-off. I don't know
>>> though if Quickbook can be made to generate HTML directly instead of
>>> XML. Joel?
>>
>> We could "easily" build a python-based BoostBook/DocBook -> xxx
>> converter.  What I'd actually do, though, is transform
>> BoostBook/DocBook into docutils' internal format, then feed that into
>> docutils and use its already-written backend writers to generate
>> whatever xxx we chose ;-).
>
> If we were to explore that path, http://sphinx.pocoo.org might be of
> interest. It's a documentation framework built on docutils, that could
> give us a uniform look and feel, plus cross referencing. Seems geared
> toward Python, but I'm sure it could be extended with whatever
> docnodes we could need.

Guys, before we get too carried away, please be aware that some of us are 
already generating very nice html and PDF docs from Docbook thankyou very 
much, and already have a significant investment in quickbook templates that 
output raw Docbook.  Unless you're planning on supporting the entire Docbook 
DTD, complete with at least the same amount of flexibility and configuration 
as the Docbook XSLT toolchain has, then I don't see an advantage, just a 
whole ton of work trying to convert to yet another format :-(

What we really should do (and I suspect could be done quite easily) is:

1) Split the build so that building the docs for library X *only* builds the 
docs for lib X, and so that building from /libs/X/doc has *exactly* the same 
effect as building from /doc/.  In other words build multiple "books" rather 
than trying (and mostly failing) to build one big "book".
2) Have the doc build automatically invoke the inspect program over the 
generated docs - to catch for broken links etc, hopefully this should 
eliminate most of the "partial build" problems.
3) Add the doc build for each library to the tests.
4) The only drawback I see, is the difficulty of one library 
linking/referencing to another, I guess it would be possible to generate a 
Docbook file containing just the link URL's to all the libraries sections 
that could be included and referenced?  Don't know if it's worth the hassle 
though?

Unfortunately most of the above represent Boost.Build changes :-(

John.