FWIW although it's already been me mentioned, Sphinx is probably the more powerful one of the two. It's used by:

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

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 to mention that it's been successfully used for everything from e-books to full reference docs.

Ryan (ライアン)
Yoko Shimomura, ryo (supercell/EGOIST), Hiroyuki Sawano >> everyone else
On Aug 7, 2017 at 10: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. 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:


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:



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