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

From: Vladimir Prus (vladimir_at_[hidden])
Date: 2008-08-18 08:46:09

John Maddock wrote:

> 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".

How exactly is it different from what we have now?

> 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 :-(

(3) is trivial, but it requires that everybody who runs tests has
docbook installed -- do you want it?

(2) is some work, but not very much. But -- do we actually need to
run inspect program for *all* test runs. After all, doc build is fairly
platform-independent, there's no point to test docs on all platforms
and compilers.

- Volodya