Re: Question regarding Boost Documentation

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2024-08-11 08:34:10

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.html
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.html

> 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.

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.