I think this is nice. So during my time trying to understand b2, I think I have a hard time understanding the "modules", like when/how the python extensions are working and what to call in order to include that in your build directly.

If you are keen on using asciidoctor, fine. However, I believe that Sphinx is in overall a much better investment, and has a wide support.

CMake (sick) documentation is written in Sphinx, using standard RST markup and a dedicated parser, and I have to say it works quite well (also, this extension should be just in python and easy to maintain).

Things to consider are to me the following:

* the overall markup:
  * this should be accessible or at least big enough to have a wide acceptance and promote contributions. I have to say I've never heard of asciidoctor so far, while ".rst" can be at least reused in several projects and is likely to have a better spread. Quickbook is not widely known, but is quite simple to handle.
  * the markup should be easy and powerful. I experienced Docbook and it is not easy at all, and quite error prone (think about cross references). I do not like .rst but this is easy. I like Quickbook a lot as well. Doxygen is not really easy because error prone, but at least provides logs/diagnostic.

* the features provided
  * is the markup rich enough, in particular for external links, embedded code, cross references, sectioning, etc
  * can you change easily the layout, and help the user navigate through the documentation nicely? In the current state of b2 doc,
  * can you generate PDF/offline doc which does not look like crap?

  * can you have a search?

  * can you generate an index easily, and play with the structure of the documentation? Can you easily change the structure? For instance, in Quickbook, restructuring breaks the URLS if you link to eg. section by the name in the documentation tree. In Sphinx, you have commands like :py:class:`` that references a global object, wherever it is in the documentation.
  * etc

* the (lack of) interplay with other tools. In boost, we have quickbook+doxygen that play together "so-so" I have to say. I personally still do not know what are the steps to generate a doc with mixed quickbook+doxygen, and this is like a black-box that is written in stone. The result is what it is (the reference sections are quite poor) and nobody is really able to maintain the dox+quickbook bindings. The requirements of having your documentation tool working well with another one for me is causing a lot of troubles, so I would rather go for a tool that can do almost everything.

Quickbook cannot (eg. parse source code), I do not know about asciidoctor, I know that Sphinx can do this and in that regard is a rather complete solution.