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.
b) a pull request modifying just the source files won't be reflected in doc/html until the next rebuild,
Right. One has to rebuild the docs locally and check in the updated files. But it's limited to one library at a time and only invoked when documentation source changes. It also fixes respectability on the person making the update. So I would hope that occasional problems would would be addressed more expediently.
c) and a pull request correctly modifying both sources and generated doc/html files may lead to lots of spurious changes to doc/html stemming from differences in the build environment (different tool versions etc).
I think I've noticed this and it IS annoying. What I notice is that often the generated documentation has tags, indices etc which get regenerated and modified and I would call spurious changes. It's cost of doing business. 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. Robert Ramey
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost