Re: Question regarding Boost Documentation

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

On 8/10/24 17:07, Robert Ramey via Boost wrote:
> 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.

Consider a situation when a user notices a typo in your library docs. He
is so fond of your library that he is willing to send a PR fixing the
typo. He notices that the generated docs committed in git, so he is
facing the following alternatives:

1. Fix the typo in the source (QuickBook/BoostBook/whatever), then setup
the toolchain to generate the html, run it to regenerate docs on his
machine. Put the entire set of changes in his PR. Then maybe notice that
his toolchain works slightly differently than yours, which results in
massive diffs in the generated html.

This is, perhaps, the most positive scenario for you, the maintainer, as
it at least preserves the source and the generated html synchronized. It
is also the least probable, as in 90% cases the user will abandon the
idea on the "setup the toolchain" step.

2. Fix the typo in the source and in the generated html, manually. You
will be lucky if the user fixes all instances of the typo in the
generated html. Downside: mismatch between source and html is possible.

3. Fix only the source, let the maintainer know that he has to rebuild
the html. Or not bother with letting you know. In any case, you merge
the PR and then you have to remember to rebuild the html (because, of
course, you might be away from your work machine when you merge the PR).
Downside: extra burden on you to rebuild the html, mismatch between
source and html if you forget.

4. Fix only the html (because "what html generation?" or "why bother
with that QuickBook/BoostBook/whatever mumbo-jumbo" or any number of
reasons). Downside: extra burden on you to backport that fix to the
source or that fix gets overwritten when you generate docs next time.
Which may be as soon as the docs are uploaded on the website.

5. Don't fix anything and walk away.

Really, don't commit auto-generated docs in git. Just don't.

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

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.