Robert Ramey
On 1/9/16 6:45 PM, Louis Dionne wrote:
Rene Rivera
writes: [...]
1. A library is required to have HTML documentation. 2. A library *can* integrate into the global Boost documentation. 3. If a library doesn't do #2 it *must* provide prebuilt HTML documentation.
Hence, even though Predef uses quickbook, it's never done #2. Therefore Predef does #3
Can't a library provide a Jamfile that generates the documentation, even if that documentation does not integrate with the global Boost documentation?
Many libraries do not "integrate with the "global Boost documentation"
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.
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.
People can browse the documentation online, which does not require any additional setup. I would posit that 95% of new users use the online documentation, and they don't use the offline documentation anyways. 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. Those wanting to get the offline documentation would simply need to clone the XYZ branch into a some directory, and then open it with their browser and everything would be in place. This would also remove the requirement for every library to have a index.html at its root, which is arguably weird. Note that this XYZ branch could also be kept as a submodule of the master repository, which wouldn't require any special action from users to get the offline documentation (besides git submodule update --init, which is already required).
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). All in all; I have no preference about exactly how this is handled, but if I have to track generated files in master or develop, then something is very wrong. Louis