Re: [boost] [release] 1.69.0 deadline for new libraries approaching

Subject: Re: [boost] [release] 1.69.0 deadline for new libraries approaching
From: Peter Dimov (pdimov_at_[hidden])
Date: 2018-10-23 18:51:28

Robert Ramey wrote:
> > Placing the .html/pdf files into the repo is one - unquestionably 
> > modular - way to do it, but it does have its downsides.
>
> Both true.
>
> downside
> - "wastes" a lot of space
> - redundant - docs could get out sync with the code.

- it complicates the process of creating and incorporating a pull request 
that includes documentation fixes. The submitter sometimes doesn't know or 
realize that the .html needs to be regenerated too, or knows it but can't 
get the script to work; or he changes the .html instead of the source.

The usual process seems to settle into submitters just submitting patches 
against the source (without having means to verify if the docs still build 
after their changes) and then the author occasionally regenerating the 
docs - if he doesn't forget, which he does.

But yes, it's a tradeoff that's worth it if you want users to have easy 
access to your documentation after cloning the repo.

For Boost libraries, I myself just point people to boost.org/libs/mylib.