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

From: John Maddock (john_at_[hidden])
Date: 2008-08-18 10:35:35

Vladimir Prus wrote:
>> 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?

Currently the docs for a number of libraries are built as a single "book" 
from within /doc/ it takes a rediculous amount of time to build, and the 
results when you build from /doc/ are quite different from when you build 
from /libs/X/doc.  It's also not possible to tweek the XSLT params for your 
specific library when using this method.  As a result several libraries have 
split away from this centralised build (including Boost.Math). 
Decentralising things would speed up building and testing docs for a 
specific library no end, changes to one library would no longer break the 
whole process, and the process would be just so much more scalable.

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

Can we rig things so that the documentation "test" is only run if the 
required tools are present in user-config.jam?  I'm assuming the incremental 
builds would actually only need to rebuild these quite infrequently anyway.

At the very least a regular test build on Win32 and Linux would have spotted 
the problems Beman had with this release much earlier (and alerted the 
appropriate developers).

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

All platforms yes, all compilers no maybe not.  The objective is to verify 
that the build proceded correctly, with no missing components.  Currently we 
have a situation where some things that should be errors aren't treated as 
such by the tools used: for example if Latex/Ghostscript are missing the 
accumulators docs will be lacking equations, but the build will "apparently" 
succeed, because Doxygen doesn't report this as a fatal error, just a 
warning :-(

It's maybe questionable whether the a general build like this should be 
dependent on those tools, but there are other situations where Doxygen 
appears not to report errors as such as well.  Checking the result with the 
inspect program would catch these failures I believe.

Again if the "test" can just be skipped if the necessary tools (boostbook, 
doxygen etc) aren't configured that would probably address most of the 
concerns?

Cheers, John.