Re: Question regarding Boost Documentation

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

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

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