On 8/11/24 11:34, Andrey Semashev wrote:
On 8/11/24 03:21, Robert Ramey via Boost wrote:
On 8/10/24 2:11 PM, Andrey Semashev via Boost wrote: Good points.
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.
BUT how is a potential or current user to access the latest html version of the documentation?
He can see it on the website. For example, depending on your definition of "latest":
https://www.boost.org/doc/libs/develop/libs/safe_numerics/doc/html/index.htm... https://www.boost.org/doc/libs/master/libs/safe_numerics/doc/html/index.html https://www.boost.org/doc/libs/release/libs/safe_numerics/doc/html/index.htm...
Is he expected to generate it himself.
If visiting the website is not an option for some reason, yes. Although the documentation is fairly readable in its source form already, so generating html is not strictly required.
I should clarify that in the paragraph above I'm assuming the documentation from an arbitrary commit from git (e.g. develop or master snapshot). Generated html documentation for Boost releases is distributed in the release package. Or, based on recent discussions, in the future it may be distributed in a separate package along with the package with the source code. So, for Boost releases, the user already has the built html.
In practice, local documentation is extremely rarely needed these days.
Then there's the question of what if the documentation the user is meant to see is located on different branches?
See the links above.
I don't think branches other than master and develop get uploaded to the website, but users aren't (supposed to be) interested in those branches either.
In general, who is expected to generate the documentation and when is he expected to do it? And what about the readable documentation out of sync with the code?
For users' perusal, the documentation is updated on the website automatically per commit to develop and master, or upon Boost releases. So the html documentation is always, though with some small delay, synchronized with git.