Re: [boost] [Boost Library Incubator] Unable to submit library

Subject: Re: [boost] [Boost Library Incubator] Unable to submit library
From: Nat Goodspeed (nat_at_[hidden])
Date: 2014-07-21 08:55:46

On Mon, Jul 21, 2014 at 7:02 AM, Paul A. Bristow
<pbristow_at_[hidden]> wrote:

> The issue of generated (mainly html) files in GIT is still a nuisance.
>
> If you are a sole developer, then it is quite easy - you simply include all the
> /doc folder with /html etc in GIT.
>
> But if you are developing *with* someone else, these generated files are a PITA.
>
> You have keep reverting the /html files every time you want to GIT pull.
>
> And you have push the updated docs every time too - and these may be quite big.
>
> I don't see a better way round this yet.  Ideas?

In fact I seem to recall some objections on this list a week or two
ago about checking generated files into source control. Please excuse
my laziness in not citing the thread.

Since the Incubator site is explicitly agnostic about how .html is
generated from source files, it's not realistic to think one could
code a "generate documentation on demand" feature into the Incubator
site -- even if resources/performance were not an issue.

Speaking from the viewpoint of "a little knowledge" (in other words,
beware!) I read through parts of the Boost.Build documentation a few
weeks ago and was a bit ashamed of the unkind remarks I myself have
made about it from time to time. It seems to me that it wouldn't be
too unreasonable to post a few cookbook Jamfile.v2 files for a
hypothetical simple Boost.Foo library, then for a somewhat less simple
Boost.Bar library: code and tests and documentation. (Let's just
stipulate that as your library's build requirements grow in
complexity, you must eventually bite the bullet and learn Boost.Build
yourself.) But a new library author, whose requirements are presumably
still pretty straightforward, could copy, tweak, iterate and ask
questions until s/he gets results.

Now we enter the realm of fantasy. Suppose someone were willing to
host a CI site on which you could register a URL to a particular
candidate library structured according to Boost library module
conventions: build/Jamfile.v2, test/Jamfile.v2, doc/Jamfile.v2. The CI
site should work with github, but any URL compatible with git clone
should also work. This site would run tests on each registered library
using Boost.Build and produce a dashboard; similarly it would run
documentation builds using Boost.Build and support a library-specific
URL by which one could retrieve its documentation (or a page saying
"Documentation not yet built" or "Documentation build errors: ...").

I blithely imagine that the test-dashboard scripting wouldn't be too
dissimilar from what people already use to run regression tests on
official Boost libraries.

I said "a CI site," but perhaps it would be better to imagine a family
of sites, each on a different hardware/OS combination. I imagine an
initial period during which you'd have to follow separate links to get
test results on Windows 7, Windows 8, OS X 8, ... At some point clever
people would provide a way to obtain a consolidated dashboard. Perhaps
the documentation generation would be yet another site, equipped with
any special software required for documentation generation.

The above speculation is intended to address the question: how could
we provide online test results and documentation for a candidate
library that uses Boost.Build, without having to commit generated
files to the repository? Consider it an existence proof: there does
seem to be at least one way.