Re: [boost] ATTENTION: Library requirements..

Subject: Re: [boost] ATTENTION: Library requirements..
From: Louis Dionne (ldionne.2_at_[hidden])
Date: 2016-01-10 17:51:22

Robert Ramey <ramey <at> rrsd.com> writes:

>
> On 1/9/16 6:45 PM, Louis Dionne wrote:
> > Rene Rivera <grafikrobot <at> gmail.com> 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