On 8/10/24 17:07, Robert Ramey via Boost wrote:
On 8/10/24 2:42 AM, Peter Dimov via Boost wrote:
Robert Ramey wrote:
From the point of view of modularization, wouldn't it make more sense just to generated inside the libraries doc/html directory? FWIW, I generate for my own libraries and check them into the git repo. I know this might seem redundant, but it relieves the user and or release of building the docs and permits the documentation to be browsed on one's local environment.
The downsides of checking in generated files (build output artifacts) are well known.
a) > E.g. a pull request modifying the doc/html files will get overwritten by
the next build,
I'm not sure I get this. One will always have the latest versions of documentation source and files checked in. I don't see a problem here.
Consider a situation when a user notices a typo in your library docs. He is so fond of your library that he is willing to send a PR fixing the typo. He notices that the generated docs committed in git, so he is facing the following alternatives: 1. Fix the typo in the source (QuickBook/BoostBook/whatever), then setup the toolchain to generate the html, run it to regenerate docs on his machine. Put the entire set of changes in his PR. Then maybe notice that his toolchain works slightly differently than yours, which results in massive diffs in the generated html. This is, perhaps, the most positive scenario for you, the maintainer, as it at least preserves the source and the generated html synchronized. It is also the least probable, as in 90% cases the user will abandon the idea on the "setup the toolchain" step. 2. Fix the typo in the source and in the generated html, manually. You will be lucky if the user fixes all instances of the typo in the generated html. Downside: mismatch between source and html is possible. 3. Fix only the source, let the maintainer know that he has to rebuild the html. Or not bother with letting you know. In any case, you merge the PR and then you have to remember to rebuild the html (because, of course, you might be away from your work machine when you merge the PR). Downside: extra burden on you to rebuild the html, mismatch between source and html if you forget. 4. Fix only the html (because "what html generation?" or "why bother with that QuickBook/BoostBook/whatever mumbo-jumbo" or any number of reasons). Downside: extra burden on you to backport that fix to the source or that fix gets overwritten when you generate docs next time. Which may be as soon as the docs are uploaded on the website. 5. Don't fix anything and walk away. Really, don't commit auto-generated docs in git. Just don't.
I see value having all the documentation for a library (source and files) in one place which moves around with the source code and is always available and in sync with with the library source. Compare this to the current system.
You do have the documentation with the library - in its source form (i.e. QuickBook/Markdown/AsciiDoc/etc.). Committing the generated html in git is similar to committing compiled binaries of your library in git.