Re: [boost] ATTENTION: Library requirements..

Subject: Re: [boost] ATTENTION: Library requirements..
From: Agustín K-ballo Bergé (kaballo86_at_[hidden])
Date: 2016-01-10 18:05:37

On 1/10/2016 7:51 PM, Louis Dionne wrote:
> Robert Ramey <ramey <at> rrsd.com> writes:
>> On 1/9/16 6:45 PM, Louis Dionne wrote:
>>> Rene Rivera <grafikrobot <at> gmail.com> 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/e471106dc850ad72f7abaf442b3570f7f34da7ed

Regards,
-- 
Agustín K-ballo Bergé.-
http://talesofcpp.fusionfenix.com