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

Subject: Re: [Boost-docs] Making Boost Doc builds more robust
From: Beman Dawes (bdawes_at_[hidden])
Date: 2008-12-04 12:59:14

On Mon, Dec 1, 2008 at 11:55 AM, Beman Dawes <bdawes_at_[hidden]> 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.
>
> 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.

Thanks to everyone who is responding to this thread, and working to improve
the process! It doesn't feel so hopeless if I know others are working on the
problems.

One of the reasons I have so much trouble with doc builds is that the log
file is next to useless for debugging problems. It is too large ( 3.1
megabyes), too verbose, and identifies things as errors that are apparently
perfectly normal. See attached.

While it is fine to have a verbose mode that lists everything that happens,
the default should be to output only error messages. At the very least
messages like "No template matches paramtype in parameter." should be
prefixed with "Error: " or "Warning: " as appropriate.

As it stands now, I'd can't even grep for "error", and get a meaningful
result. See below for the current release branch result of such a grep. Are
these really errors?

Thanks,

--Beman

Error: no ID for constraint linkend:
boost_proto.users_guide.getting_started.
Error: no ID for constraint linkend: boost_proto.users_guide.front_end.
Error: no ID for constraint linkend:
boost_proto.users_guide.intermediate_form.
Error: no ID for constraint linkend: boost_proto.users_guide.back_end.
Error: no ID for constraint linkend: boost_proto.users_guide.examples.
Error: no ID for constraint linkend: boost_tr1.unsupported.special.
Error: no ID for constraint linkend: boost_tr1.unsupported.unordered_map.
Error: no ID for constraint linkend: boost_tr1.unsupported.unordered_set.
Error: no ID for constraint linkend:
unordered.rationale.swapping_containers_with_unequal_allocators
.
Error: no ID for constraint linkend:
unordered.rationale.swapping_containers_with_unequal_allocators
.
Error: no ID for constraint linkend:
unordered.rationale.swapping_containers_with_unequal_allocators
.
Error: no ID for constraint linkend:
unordered.rationale.swapping_containers_with_unequal_allocators
.
Error: no ID for constraint linkend:
unordered.rationale.swapping_containers_with_unequal_allocators
.
Error: no ID for constraint linkend:
unordered.rationale.swapping_containers_with_unequal_allocators
.
Error: no ID for constraint linkend:
unordered.rationale.swapping_containers_with_unequal_allocators
.
Error: no ID for constraint linkend:
unordered.rationale.swapping_containers_with_unequal_allocators
.
Error: no ID for constraint linkend: xpressive.reference.
Error: no ID for constraint linkend: bbv2.reference.commandline.
Error: no ID for constraint linkend: bbv2.jam.
Error: no ID for constraint linkend: bbv2.jam.
Error: no ID for constraint linkend: bbv2.jam.
Error: no ID for constraint linkend: bbv2.jam.
Error: no ID for constraint linkend: bbv2.jam.
Error: no ID for constraint linkend: bbv2.jam.
Error: no ID for constraint linkend: bbv2.jam.
Error: no ID for constraint linkend: bbv2.jam.
Error: no ID for constraint linkend: bbv2.reference.commandline.
Error: no ID for constraint linkend: bbv2.reference.commandline.