With boost library documentation there are two factors that are both important:

• that the library docs can be built for any individual library, relatively conveniently, simply, directly.

• that the library docs can be compiled by release-tools and published in full release archives.

The difficulties with antora docs in boostorg/url are:

• https://gitlab.com/antora/antora/-/issues/895 "Document generation fails for Git Submodules". Since boostorg uses submodules, developers out in the world will encounter this. Attempting to add CI jobs also ran into this problem.

• The build script "build_antora.sh" is complicated, and has a large number of dependencies, including the fact it downloads "all of boost". And npm modules.

• It's not standardized. It's not the same method as other libs, which in boost is helpful.

An individual lib contributor would not seem to benefit from a "build_antora.sh" system since it's more complex and more work. The Jamfile method of building one library is simple, basic, quick, convenient.

Here is an idea:

Since Antora is based on AsciiDoc at some level, compose the docs for boostorg/url and other similar libaries using AsciiDoc and Jamfiles, and build them as normal, for each library. For each individual library, nothing changes, and it doesn't know about Antora.

Then, in boostorg/release-tools, collate and compile any discovered AsciiDoc libs into an antora collection. This may involve generating playbooks and dynamically modifying the text content of each library doc. Well, this is just an idea and I do not know if it would be feasible.