Re: [Boost-docs] Making Boost Doc builds more robust

Subject: Re: [Boost-docs] Making Boost Doc builds more robust
From: John Maddock (john_at_[hidden])
Date: 2008-12-02 10:27:08

Beman Dawes wrote:
>> Right now the Boost documentation build is a serious problem from the
>> standpoint of release management.
>>
>> There is no way to tell if doc builds are working other than asking
>> people to look at the results. This prevents automatic notification
>> if the build process breaks. It seems to me the first step in making
>> doc builds more robust is adding a boost-root/doc/test directory
>> with a Jamfile and test cases that can be used to debug the problems.
>>
>> Documentation builds only work for me on Linux. Builds on Windows
>> work for Eric, IIUC, but not for me. This prevents me from running
>> automatic daily release branch builds. It would be a lot easier to
>> debug this problem if we had a test setup.

Nod.

However, building on Windows works for me too, so <shrug>.

>> Once we have a test setup that can detect if an error occurs, we can
>> work on ensuring that error messages (1) say what probem occurred and
>> (2) say what to do to correct the problem.

Yeh, detecting errors is the hard part, things I've noticed:

* Doxygen not failing if it encounters an error (did we fix the accumulators 
build to depend on latex etc being in the path?  It appears not?).
* Doxygen bbv2 rule emits a message:
    "The system could not find the file specified"
on windows because it tries to delete files that don't exist *if the Jamfile 
hasn't been previously invoked*.  This is particular annoying because the 
error message is identical to the one from a missing latex install :-(
* Endless (and quite pointless?) messages from the Boostbook->Docbook XSL 
transform.
* Quickbook not failing if it encounters an error.
* FO processors not failing if they encounter an error (missing images).
* No way to automatically check if the built HTML docs are OK (would the 
inspect tool help here - verify that all images and links are correct?).

John.