Re: [Boost-build] B2 documentation..

Subject: Re: [Boost-build] B2 documentation..
From: Raffi Enficiaud (raffi.enficiaud_at_[hidden])
Date: 2017-08-09 05:51:45

Le 09.08.17 à 03:09, Rene Rivera via Boost-build a écrit :
> On Tue, Aug 8, 2017 at 4:18 AM, Raffi Enficiaud via Boost-build
> <boost-build_at_[hidden] <mailto:boost-build_at_[hidden]>> 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?

They extended Sphinx to parse their .cmake modules, such that they have 
the documentation of the module and function directly extracted from the 
source code, and at the same time they have some cmake "terminology" in 
Sphinx directly.

The markup is the same, it just starts with "#.rst" or something, and 
they made Sphinx understand the CMake "domain" (the CMake notions such 
as function, module ... are understood by Sphinx and used for eg. proper 
cross reference, such as ":command:`find_package`" or 
:variable:`Matlab_ROOT_DIR`).

https://cmake.org/cmake/help/v3.3/manual/cmake-developer.7.html#help

Something I wrote:
https://github.com/Kitware/CMake/blob/master/Modules/FindMatlab.cmake

Although I have never done that myself, I would not say it is a big deal:
https://github.com/Kitware/CMake/blob/master/Utilities/Sphinx/cmake.py

>
>     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.

At some point, you will provide functions that exists in b2 modules 
only, and you will want to document those. In Quickbook terminology, 
doxygen is considered as "reference", but this is only in quickbook 
terms as Doxygen is a complete solution (pages and user doc, as well as 
doc extracted from sources).

The point here is that, during the documentation process, being able to 
have in-source markup and having that extracted is an important feature 
you may want to have. But as you are pointing down your reply, 
asciidoctor can do the same.

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

Search is useful ... for searching :) To me, search fills somehow the 
gap between the structure of the doc provided by the developer and what 
the user "expects" (if the user expects or not anything). I believe this 
is a very nice feature.

>
>
>       * 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
> <http://readthedocs.org> and devdocs.io <http://devdocs.io> easily.

Yes. I would like to mention that readthedoc can host other type of 
generated HTML, and Sphinx is not mandatory:

http://breathe.readthedocs.io/en/latest/readthedocs.html
http://dynet.readthedocs.io/en/latest/doc_style.html

Since readthedoc is generating the doc, you cannot run any executable 
there, but it seems to be possible to run python with any set of packages.

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

Nice!