Re: [Boost-build] B2 documentation..

Subject: Re: [Boost-build] B2 documentation..
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2017-08-09 01:09:41

On Tue, Aug 8, 2017 at 4:18 AM, Raffi Enficiaud via Boost-build <
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?

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

Indeed.

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