On 1/10/2016 7:51 PM, Louis Dionne wrote:
Robert Ramey
writes: On 1/9/16 6:45 PM, Louis Dionne wrote:
Rene Rivera
writes: It would be straightforward to require that doing `cd doc && b2` generates the documentation into `doc/html`, with index.html as an entry point. You might think it would be straightforward - but it's not. The toolchain is long and finicky.
??? How is it more difficult to require `cd doc && b2` to generate the documentation rather than having it in place already? You already have to do `cd doc && b2` for libraries that integrate with the rest of Boost anyway.. There must be something I'm not getting.
In order for `cd doc && b2` to work, one first need to have all the dependencies in order. This alone is a considerable amount of work (see https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted), and nobody should go through that much trouble just to see html docs.
Committing pre-generated documentation is a big no-no, at least for me.
I'm aware that doing so is redundant. BUT it provides anyone who want's to browse boost just to do so directly, without building anything. For example, anyone can just start browsing the repo master branch without doing downloading or building anything. This is huge for new users of boost.
The way I see it, there should be a separate branch, say XYZ, which contains the documentation. This branch would simply need to be kept up to date with the documentation of every Boost library, which could be done by doing `cd doc && b2` in library's doc/ directory, and then copying the result to the right place. If someone wants to store the pre-generated documentation, this the Jamfile in `doc/` could just do nothing.
+1
The extra space used seems a small price to pay for this benefit.
It's not just about extra space. Source control is for _source_ files, not generated stuff. I don't want generated files to appear in the commit history of a code branch (but another branch like gh-pages is fine).
By way of example, this is the kind of noise committing generated documentation can yield: https://github.com/boostorg/hana/commit/e471106dc850ad72f7abaf442b3570f7f34d... Regards, -- Agustín K-ballo Bergé.- http://talesofcpp.fusionfenix.com