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.