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.