On Tue, Aug 8, 2017 at 4:18 AM, Raffi Enficiaud via Boost-build <boost-build@lists.boost.org> wrote:

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.

Good to know that does need more explaining. 

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.

Point taken.
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).

Hmm.. What extension? 

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, flexible, simplicity of asciidoc is something I like. So I understand that sentiment. But not, documenting in the style of doxygen, i.e. classes and methods, is not what I'm looking for as that's not the kind of documentation b2 needs.

* 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?

I only find search useful for reference docs. But that's a good point.
  * 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

Another item.. Can you export to sites like readthedocs.org and devdocs.io easily.
* 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.

That's a good point. 
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.

Asciidoctor doesn't try to parse code. It supports a variety of other libraries to do the syntax coloring. You can select which one you want to use. As for extracting documentation from from source code.. It uses a general mechanism to extract documentation from any text file. And the that extraction can be plugged into any use within the tool. The extraction is also rather flexible as it supports different subsets in the same text files. Also it can do it in a scoped manner. Without ever needing to learn how to parse different languages.

-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net
-- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail