Boost logo

Boost :

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.


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk