Re: Proposal: Abandoning monolithic Boost documentation.

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2025-04-18 17:03:40

On 18 Apr 2025 19:53, René Ferdinand Rivera Morell via Boost wrote:
> Today, in slack, we had a discussion on problems with building the
> monolithic docs. For context what I'm calling the monolithic docs are these
> <https://www.boost.org/doc/libs/1_88_0/doc/html/libraries.html>. The main
> problem that was raised is that a failure in one library causes all the
> docs to disappear. That problem is due to the nature of DocBook, XSLT, and
> the single monolithic generation. This is not something that can be
> resolved at the build system leve. The one solution is to abandon the
> monolithic build. And instead move to only having per library documentation
> builds. Hence..
> 
> I am proposing we abandon the monolithic documentation build. The benefits:
> 
> * No longer missing docs from problems in individual libraries.
> * It's modular. I.e. libraries would build, and include, their docs in the
> modular layout.
> 
> Do note that most libraries, more than 2/3, already use modular
> documentation. So technically this would be completing the modular
> transition that has already been happening.
> 
> Thoughts?

I'm ok with this, but I think all of my libraries already use modular
doc builds.

I imagine, the majority of libraries that still build in the root doc
directory are the old ones, probably not well maintained. Who's going to
update those and is there a description of what needs to be done? I
think, some changes to superproject were also required.