B2 documentation..

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

B2 documentation..

Boost - Build mailing list
As has been mentioned in the past there's the impression that the B2 documentation is lacking. As part of my efforts to move b2 forward I'm looking at option for reworking the documentation. And for various reasons I'm not fond of continuing with the current straight BoostBook/DocBook documentation. My preferred approach is to use a combination of user manual documentation, which we have but needs to be redone, and embedded reference documentation. For the latter I mean having documentation in source code an having a documentation tool extract it and incorporate with the user manual. For Predef I did this with QuickBook extracting from header files. But given the limitations of QuickBook I'm wanting to find an external tool that does the equivalent. So far I've looked at Sphinx and Asciidoctor <http://asciidoctor.org/>. To me Asciidoctor seems like the closer match to the QuickBook features. So I'm here for two reasons:

First..

I'd like to show an example of asciidoctor docs for B2. The experiment I did was two write an new asciidoctor b2 tool. The source for that tool has documentation embedded in it. Here's what that looks like:


I've incorporated that into the general b2 documentation. By producing docbook from that source with the asciidoctor tool and including it as one of the appendices. And hence it has the same appearance of the general Boost documentation. Here's how that documentation looks like:


Second..

I'm looking for feedback and suggestions. Are there other tools we should be considering? What do you think of asciidoctor? Any other thoughts with regards to documenting b2?

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

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
On 8/7/17 8:03 PM, Rene Rivera via Boost-build wrote:

as a habitual complainer about boost b2 and boost documentation in
general, I'd like to make some observations.

> As has been mentioned in the past there's the impression that the B2
> documentation is lacking. As part of my efforts to move b2 forward I'm
> looking at option for reworking the documentation. And for various
> reasons I'm not fond of continuing with the current straight
> BoostBook/DocBook documentation.

I recently had occasion to study the Boost B2 documentation we currently
have.  It's actually OK - particularly in the documentation of commands
and such.  But in trying to move on to other concepts in b2 itself,
searching for jamroot, *-config.jam etc, it falls short.  I don't think
this is actually documentable.  When trying to describe how b2 works,
one is going to discover that b2 is too inherently complex and should be
restructured to make it more understandable.  If b2 is considered
fixed in stone, you won't be able to document it.

> My preferred approach is to use a
> combination of user manual documentation, which we have but needs to be
> redone, and embedded reference documentation. For the latter I mean
> having documentation in source code an having a documentation tool
> extract it and incorporate with the user manual.

I believe that, after much effort, this will yield disappointing
results.  It might work for the commands and rules built-in, but these
are already OK.  It won't work for the really hard part of b2 -
features, properties syntax and semantics.

> Second..
>
> I'm looking for feedback and suggestions. Are there other tools we
> should be considering? What do you think of asciidoctor? Any other
> thoughts with regards to documenting b2?
>
> --
> -- Rene Rivera
> -- Grafik - Don't Assume Anything
> -- Robot Dreams - http://robot-dreams.net <http://robot-dreams.net/>
> -- rrivera/acm.org
> <http://acm.org/> (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail
>
>
> _______________________________________________
> Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
>

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
On Mon, Aug 7, 2017 at 10:32 PM, Robert Ramey via Boost-build <[hidden email]> wrote:
On 8/7/17 8:03 PM, Rene Rivera via Boost-build wrote:

as a habitual complainer about boost b2 and boost documentation in
general, I'd like to make some observations.

:-) 

As has been mentioned in the past there's the impression that the B2 documentation is lacking. As part of my efforts to move b2 forward I'm looking at option for reworking the documentation. And for various reasons I'm not fond of continuing with the current straight BoostBook/DocBook documentation.

I recently had occasion to study the Boost B2 documentation we currently have.  It's actually OK - particularly in the documentation of commands and such. 

I've read it a few times.. And recently I started reading front to back. And there are certainly "issues" with it...
 
But in trying to move on to other concepts in b2 itself, searching for jamroot, *-config.jam etc, it falls short.  I don't think this is actually documentable.

I think it's documentable.. But even if it's not actually documentable, having something is going to be better than nothing. 
 
  When trying to describe how b2 works, one is going to discover that b2 is too inherently complex and should be restructured to make it more understandable.  If b2 is considered
fixed in stone, you won't be able to document it.

It's definitely not fixed in stone. And part of me writing new tools and writing new documentation is to find the complexities and inconsistencies. And either fix them or document them with warnings (or some combination). 

My preferred approach is to use a combination of user manual documentation, which we have but needs to be redone, and embedded reference documentation. For the latter I mean having documentation in source code an having a documentation tool extract it and incorporate with the user manual.

I believe that, after much effort, this will yield disappointing results.  It might work for the commands and rules built-in, but these
are already OK.  It won't work for the really hard part of b2 - features, properties syntax and semantics.

Embedded documentation is definitely *not* for what you call "semantics". That's what a user manual is for. But right now there's a lot in b2 that is "not documented" in the sense that it's not in the HTML. Although much of it is in comments in code. But as I've seen over the years.. The CLI "--help" system is just not used by users. And I don't blame users, that's entirely my fault (I mean that personally as I wrote that system). My plan for docs is to bring to light that existing documentation and improve it along the way (as above to deal with implementation issues also) and to add documentation, and visibility, to all the built-in tools and utilities that are currently "hidden". I also hope that this style will make it easier for outside contributions. As has been the case for Predef.

There's one more item that might be relevant given your mention of documenting "features" and "semantics".. One common way to do that is through examples. I had previously also experimented with the same manual+embedded documentation but for the existing examples, but with QuickBook. Here's source for one of the cleaned up examples:


And the resulting HTML page:


I know you have ideas on how to write documentation.. And I might get the chance to hear about them at CppCon.. But this is what has worked for me.

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

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On 8/7/2017 11:03 PM, Rene Rivera via Boost-build wrote:

> As has been mentioned in the past there's the impression that the B2
> documentation is lacking. As part of my efforts to move b2 forward I'm
> looking at option for reworking the documentation. And for various
> reasons I'm not fond of continuing with the current straight
> BoostBook/DocBook documentation. My preferred approach is to use a
> combination of user manual documentation, which we have but needs to be
> redone, and embedded reference documentation. For the latter I mean
> having documentation in source code an having a documentation tool
> extract it and incorporate with the user manual. For Predef I did this
> with QuickBook extracting from header files. But given the limitations
> of QuickBook I'm wanting to find an external tool that does the
> equivalent.

What are the limitations with Quickbook you are finding ? I do not want
to start a debate about it but I am just curious why you do not find it
adequate for Boost Build docs.

> So far I've looked at Sphinx and Asciidoctor
> <http://asciidoctor.org/>. To me Asciidoctor seems like the closer match
> to the QuickBook features. So I'm here for two reasons:
>
> First..
>
> I'd like to show an example of asciidoctor docs for B2. The experiment I
> did was two write an new asciidoctor b2 tool. The source for that tool
> has documentation embedded in it. Here's what that looks like:
>
> <https://github.com/boostorg/build/blob/feature/asciidoctor/src/tools/asciidoctor.jam>
>
> I've incorporated that into the general b2 documentation. By producing
> docbook from that source with the asciidoctor tool and including it as
> one of the appendices. And hence it has the same appearance of the
> general Boost documentation. Here's how that documentation looks like:
>
> <https://grafikrobot.github.io/b2doc/extra-tools.html>
>
> Second..
>
> I'm looking for feedback and suggestions. Are there other tools we
> should be considering? What do you think of asciidoctor? Any other
> thoughts with regards to documenting b2?
>
> --
> -- Rene Rivera
> -- Grafik - Don't Assume Anything
> -- Robot Dreams - http://robot-dreams.net <http://robot-dreams.net/>
> -- rrivera/acm.org
> <http://acm.org/> (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
Le 08.08.17 à 05:57, Rene Rivera via Boost-build a écrit :

> On Mon, Aug 7, 2017 at 10:32 PM, Robert Ramey via Boost-build
> <[hidden email] <mailto:[hidden email]>> wrote:
>
>     On 8/7/17 8:03 PM, Rene Rivera via Boost-build wrote:
>
>     as a habitual complainer about boost b2 and boost documentation in
>     general, I'd like to make some observations.
>
>
> :-)
>
>         As has been mentioned in the past there's the impression that
>         the B2 documentation is lacking. As part of my efforts to move
>         b2 forward I'm looking at option for reworking the
>         documentation. And for various reasons I'm not fond of
>         continuing with the current straight BoostBook/DocBook
>         documentation.
>
>
>     I recently had occasion to study the Boost B2 documentation we
>     currently have.  It's actually OK - particularly in the
>     documentation of commands and such.
>
>
> I've read it a few times.. And recently I started reading front to back.
> And there are certainly "issues" with it...
>
>
>     But in trying to move on to other concepts in b2 itself, searching
>     for jamroot, *-config.jam etc, it falls short.  I don't think this
>     is actually documentable.
>
>
> I think it's documentable.. But even if it's not actually documentable,
> having something is going to be better than nothing.
>
>
>       When trying to describe how b2 works, one is going to discover
>     that b2 is too inherently complex and should be restructured to make
>     it more understandable.  If b2 is considered
>     fixed in stone, you won't be able to document it.
>
>
> It's definitely not fixed in stone. And part of me writing new tools and
> writing new documentation is to find the complexities and
> inconsistencies. And either fix them or document them with warnings (or
> some combination).
>
>         My preferred approach is to use a combination of user manual
>         documentation, which we have but needs to be redone, and
>         embedded reference documentation. For the latter I mean having
>         documentation in source code an having a documentation tool
>         extract it and incorporate with the user manual.
>
>
>     I believe that, after much effort, this will yield disappointing
>     results.  It might work for the commands and rules built-in, but these
>     are already OK.  It won't work for the really hard part of b2 -
>     features, properties syntax and semantics.
>
>
> Embedded documentation is definitely *not* for what you call
> "semantics". That's what a user manual is for. But right now there's a
> lot in b2 that is "not documented" in the sense that it's not in the
> HTML. Although much of it is in comments in code. But as I've seen over
> the years.. The CLI "--help" system is just not used by users. And I
> don't blame users, that's entirely my fault (I mean that personally as I
> wrote that system). My plan for docs is to bring to light that existing
> documentation and improve it along the way (as above to deal with
> implementation issues also) and to add documentation, and visibility, to
> all the built-in tools and utilities that are currently "hidden". I also
> hope that this style will make it easier for outside contributions. As
> has been the case for Predef.
>
> There's one more item that might be relevant given your mention of
> documenting "features" and "semantics".. One common way to do that is
> through examples. I had previously also experimented with the same
> manual+embedded documentation but for the existing examples, but with
> QuickBook. Here's source for one of the cleaned up examples:
>
> <https://github.com/boostorg/build/tree/feature/asciidoctor/example/variant>
>
> And the resulting HTML page:
>
> <https://grafikrobot.github.io/b2doc/bbv2/examples/build_variants.html>
>
> I know you have ideas on how to write documentation.. And I might get
> the chance to hear about them at CppCon.. But this is what has worked
> for me.

Hi there,

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.

Just my thoughts.

Cheers,
Raffi

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
On 8 August 2017 at 10:18, Raffi Enficiaud via Boost-build
<[hidden email]> wrote:
>
>   * 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.

I have no interest in a debate about which is the bestest
documentation system, but to answer the question, in quickbook you can
use anchors (e.g [#link.something]), which can be moved around and
survive restructuring.<div
id="DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2"><br />
<table style="border-top: 1px solid #D3D4DE;">
        <tr>
        <td style="width: 55px; padding-top: 13px;"><a
href="https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail"
target="_blank"><img
src="https://ipmcdn.avast.com/images/icons/icon-envelope-tick-round-orange-animated-no-repeat-v1.gif"
alt="" width="46" height="29" style="width: 46px; height: 29px;"
/></a></td>
                <td style="width: 470px; padding-top: 12px; color: #41424e;
font-size: 13px; font-family: Arial, Helvetica, sans-serif;
line-height: 18px;">Virus-free. <a
href="https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail"
target="_blank" style="color: #4453ea;">www.avast.com</a>
                </td>
        </tr>
</table><a href="#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2" width="1"
height="1"></a></div>
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
Le 08.08.17 à 11:55, Daniel James via Boost-build a écrit :

> On 8 August 2017 at 10:18, Raffi Enficiaud via Boost-build
> <[hidden email]> wrote:
>>
>>   * 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.
>
> I have no interest in a debate about which is the bestest
> documentation system,

Good, me neither :)

> but to answer the question, in quickbook you can
> use anchors (e.g [#link.something]), which can be moved around and
> survive restructuring.

Yes I know, but I have found it hard to maintain and I prefer having the
section implicit links directly (that I can just see by opening the
browser and clicking on the section).

The links in Sphinx carry some semantics as well, like :py:class:`some
class`, a bit a la [classref ] , with the difference that the referenced
entity is living in the same documentation system (and not in eg Doxygen).

Do not get me wrong, I like the simplicity/expressivity of Quickbook,
just I have found a bit poor the "reference like" documentation support
(link to externally managed documentation).

Raffi

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On Tue, Aug 8, 2017 at 12:46 AM, Edward Diener via Boost-build <[hidden email]> wrote:
On 8/7/2017 11:03 PM, Rene Rivera via Boost-build wrote:
As has been mentioned in the past there's the impression that the B2 documentation is lacking. As part of my efforts to move b2 forward I'm looking at option for reworking the documentation. And for various reasons I'm not fond of continuing with the current straight BoostBook/DocBook documentation. My preferred approach is to use a combination of user manual documentation, which we have but needs to be redone, and embedded reference documentation. For the latter I mean having documentation in source code an having a documentation tool extract it and incorporate with the user manual. For Predef I did this with QuickBook extracting from header files. But given the limitations of QuickBook I'm wanting to find an external tool that does the equivalent.

What are the limitations with Quickbook you are finding ? I do not want to start a debate about it but I am just curious why you do not find it adequate for Boost Build docs.

Briefly..

* No general mechanism for extracting embedded docs. Only Python and CPP embedded docs are truly supported (I kludged it for jam files but not completely).
* Limited to BoostBook output. Which limits it to the BoostBook XSLT. Which limits it to one style of documentation.
* No support for fun things like diagrams.
* No easy way to extend it.
* Limited languages for syntax styling.

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

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
On 8 August 2017 at 13:23, Rene Rivera via Boost-build
<[hidden email]> wrote:
>
> * Limited to BoostBook output. Which limits it to the BoostBook XSLT. Which
> limits it to one style of documentation.

I think you can treat quickbook's output as docbook. You just need to
avoid the boostbook specific features (which I think is just 'library'
doc types and C++ reference tags). So you can use alternative docbook
styles.

I'm also working on html output, which should eventually have theme
support. Or at least will be able to output xml that can be
post-processed.
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On 8/8/17 5:23 AM, Rene Rivera via Boost-build wrote:
>.
> * Limited to BoostBook output. Which limits it to the BoostBook XSLT.
> Which limits it to one style of documentation.

Hmmm - I would say the opposite.  That is the BoostBook -> Docbook
permits one to de-couple the content from the format so that one can
generate output as html pages, pdf, ebook.  I have done all of these
with the system.  One can also use xslt to tweak the output to taste. It
IS a pain in the neck.  But it can do anything and once it's working
it's quite reliable.

> * No support for fun things like diagrams.
> * No easy way to extend it.
> * Limited languages for syntax styling.

Since quickbook generates boostbook I would expect that trying to
specify formats with quickbook would not be a productive endeavor.


>
> --
> -- Rene Rivera
> -- Grafik - Don't Assume Anything
> -- Robot Dreams - http://robot-dreams.net <http://robot-dreams.net/>
> -- rrivera/acm.org
> <http://acm.org/> (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail
>
>
> _______________________________________________
> Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
>

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
 
I would like to point out that the Python port has become much more stable and a lot more feature-complete recently
 
And since Sphinx plays nicely with Python, Python natively supports docstrings (actual object attributes), and packages like Redbaron allow for parsing even comments for extended functionality (like documenting features), I'd vote for Sphinx. I know someone else mentioned it, but I haven't heard of Asciidoctor either, so I don't know how widely known it is.
 
Ultimately, however, either choice seems good to me.
 
Aaron
 
> I'm looking for feedback and suggestions. Are there other tools we should be considering? What do you think of asciidoctor? Any other thoughts with regards to documenting b2?

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On Tue, Aug 8, 2017 at 8:59 AM, [hidden email] <[hidden email]> wrote:
FWIW although it's already been me mentioned, Sphinx is probably the more powerful one of the two. It's used by:

I'm not ruling it out.. Which is why I asked what other thought :-) But.. 

- The Linux kernel (!).
- CMake.
- LLVM.
- Python.
- Many, many, many more projects.

Popularity is not a wining argument around here ;-)
 
It's insanely flexible (you can make plugins in a heartbeat, and it's incredibly easy to theme), and it supports an insane amount of programming languages.

Not so interested in making plugins. I've done enough tweaking of Quickbook to not want to go down that route. But having others who can do plugins is useful. 



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

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On Tue, Aug 8, 2017 at 11:46 AM, Robert Ramey via Boost-build <[hidden email]> wrote:
On 8/8/17 5:23 AM, Rene Rivera via Boost-build wrote:
.
* Limited to BoostBook output. Which limits it to the BoostBook XSLT. Which limits it to one style of documentation.

Hmmm - I would say the opposite.  That is the BoostBook -> Docbook permits one to de-couple the content from the format so that one can generate output as html pages, pdf, ebook.  I have done all of these with the system.  One can also use xslt to tweak the output to taste. It IS a pain in the neck.  But it can do anything and once it's working it's quite reliable.

True.. But I obviously meant that it can't generate anything else by itself. Having options of backend toolchains is an important attribute. Having the docbook toolchain be the only option is aggravating. I.e. having options is nice.

* No support for fun things like diagrams.
* No easy way to extend it.
* Limited languages for syntax styling.

Since quickbook generates boostbook I would expect that trying to specify formats with quickbook would not be a productive endeavor.

I don't see how that relates to those three points.

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

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On Tue, Aug 8, 2017 at 4:18 AM, Raffi Enficiaud via Boost-build <[hidden email]> 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

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
In reply to this post by Boost - Build mailing list


On Aug 7, 2017 11:05 PM, "Rene Rivera via Boost-build" <[hidden email]> wrote:

> I'm looking for feedback and suggestions. Are there other tools we should be considering?

I fully agree with what others have said about sphinx (and docutils / ReST as the underlying technology).
Popularity aside, I believe it is an enormous advantage for a tool to have many users, as that makes it likely that the tool is well tested and supported (e.g. by those same users).

> What do you think of asciidoctor? Any other thoughts with regards to documenting b2?

Perhaps that's just reflective of my own way to learn new tools and languages, but one type of documentation I'm often missing is one on a conceptual level. And while there is some glossary with terms and concepts, this is not nearly as complete in its description as would be necessary to allow me to reason with these terms.
Just look at the ongoing discussion between Steven and myself (mostly just about how targets are defined and how information "flows" between them in terms of features /properties).
For any but the most trivial use cases, this seems quite important information indeed (and also from judging from questions other users have, either about behaviour they seek or error messages they try to comprehend).

(My believe that the underlaying model is more complex than necessary is one of the main driving forces for my working on Faber... :-) )

    Stefan


_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
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
> <[hidden email] <mailto:[hidden email]>> 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!

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: B2 documentation..

Boost - Build mailing list
In reply to this post by Boost - Build mailing list

 

We’ve been using Doxygen for a several projects:

flexible output options HTML, PDF, XML,

flexible markup,

pluggable language support.

 

http://www.stack.nl/~dimitri/doxygen/

 

Another nice thing, is it supports a fairly generic flavor of markdown as markup option; which is compatible with github/stash websites.

Active enough projects that bugs get fixed.  

 

(I didn’t see any clear requirements at the beginning of the thread, so I’m highlighting what was important for our use)

 

Brian  Kuhl


_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Loading...