Re: Proposal: Abandoning monolithic Boost documentation.

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2025-04-22 21:30:11

On 22 Apr 2025 22:50, Дмитрий Архипов via Boost wrote:
> вт, 22 апр. 2025 г. в 22:26, Robert Ramey via Boost <boost_at_[hidden]>:
>>
>> Each library will have its html files to document it.  Would it not be
>> possible to write one (fancy) javascript to generate the the page above
>> just by scanning all the released libraries html?
>>
>> Then we'd have everything we have now without any depencies outside any
>> library. Looks practical to me.
> 
> The problem with storing generated HTML files in the project has
> already been mentioned multiple times: people regularly forget to
> update those HTML files when they change documentation. There's an
> even worse problem when someone updates a HTML file, but not the
> source file, and the changes are lost on the next regeneration.

I don't think anyone suggested storing (in git) the generated html. I
know some libraries do that, but maintainers of those libraries have
taken the responsibility to keep the source and generated content in
sync. Whether the docs are modularized or not is orthogonal to that.

I think, what Robert suggested is to just build the monolithic docs from
modularized. As far as html goes, nothing needs to be done as we already
list all libraries on the website, whether they use modularized or
centralized docs. For pdf, I don't think it would be easy or at all
possible to generate a single pdf from multiple libraries. Though I
doubt there is any demand for that nowdays.

> And it doesn't solve the main problem with having multiple
> documentation formats in the project: that a contributor will have a
> hard time figuring out how to build docs for the library he is
> interested in. This is because that contributor would still have to
> get the necessary tool.

This also doesn't change with this proposal. If anything, it has the
potential to increase the tool diversity.