On Mon, Jul 21, 2014 at 7:02 AM, Paul A. Bristow <pbristow@hetp.u-net.com> 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.