Re: Proposal: Abandoning monolithic Boost documentation.

From: Alexander Grund (alexander.grund_at_[hidden])
Date: 2025-04-23 09:25:04

Am 23.04.25 um 05:24 schrieb Robert Ramey via Boost:
> On 4/22/25 2:30 PM, Andrey Semashev via Boost wrote:
>
>> I don't think anyone suggested storing (in git) the generated html.
> My libraries do that.  Basically it so anyone who download the git 
> repo as a zip file (E.G. a user) can read the documentation right away 
> and know that it is in sync with the code.

I don't agree with the last part: If the built documentation (HTML/PDF) 
is in the repo I cannot "know" if it is up to date as I don't know how 
often it is regenerated from its prime source.
E.g. if it contains code snippets taken from the actual source code and 
that has changed without remembering that it is referenced, and hence 
requires doc regeneration, the documentation will be outdated.

As Дмитрий Архипов just noted: People make mistakes and forget stuff.
Or contributors get confused if there are only HTML pages or they need 
to update something else.

To put it a bit blunt: The only safe way to ensure the (built) 
documentation is not outdated is to not have them in regular sources.
On fixed points in time it should be (re)generated and distributed with 
the sources at that point in time, i.e. releases.

Of course those mistakes with forgotten updates when keeping the 
generated artifacts in the repo can be mitigated by a CI check that e.g. 
generates the sources and fails if there are differences.
This also has the advantage of contributors being able to do that in PRs 
touching documentation.