Migrate documentation to Asciidoc

[mloskot]

The Asciidoc has been in use in Boost for long time, see Asciidoc, an alternative for documentation. More and more libraries seem to be converting their documentation to Asciidoc, for example

• refactor documentation to use asciidoc array#26
• MP11 in boostorg/mp11@f93e0fa

If there are no objections, we should consider migration from Sphinx to Asciidoc for unified UI/UX with the rest of Boost docs and to solve issues like

• API Reference documentation is not readable using a dark theme #782

References

• https://www.boost.org/doc/contributor-guide/docs/content.html

[mloskot]

I've asked on cpplang:

which library would be the best example how it should be done after the Boost website, docs, etc. revamp?

and received useful answer:

Depends on if you want a single page doc (good for small libs) or multi page
Single page look at boost.mp11
Multipage check out boost.url

and

Boost.JSON also uses asciidoc, but achieves multipage with different tools

I thought Asciidoc-based docs in Boost are always single-page. The multi-page variant may be suitable for GIL.

Do we have any preferences?
/cc @sdebionne @planetmarshall @boostorg/gil

[sdebionne]

I think that GIL is a rather large library so I would go for the multi-page variant too.

[mloskot]

I agree with you @sdebionne

I've received some more feedback on cpplang to my question from #783 (comment), on tooling requirement:

only asciidoc, single page: one of Peter libs, e.g. variant2, mp11, compat
asciidoc + antora (multiple pages): unordered
asciidoc + antora + mrdocs (like Doxygen, but generates asciidoc): redis or url (probably Redis is smaller and simpler)
asciidoc + antora + mrdocs + standalone doc folder : openmethod