Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Dave Abrahams (dave_at_[hidden])
Date: 2011-09-27 15:53:36

on Tue Sep 27 2011, Mateusz Loskot <mateusz-AT-loskot.net> wrote:

> On 27/09/11 01:09, Dean Michael Berris wrote:
>> On Tue, Sep 27, 2011 at 9:46 AM, Mateusz Loskot <mateusz_at_[hidden]>
>
>> wrote:
>>> 
>>> Has anyone considered it?
>> 
>> I/we use it in cpp-netlib for both docs and the website.
>
> So, you write it in reStructuredText, right?
>
>>> Would it be valid to discuss Sphinx for Boost?
>> 
>> I for one would welcome discussion about it.
>
> The major problem I have with the current Boost documentation framework
> is too big diversity of documenting tools and workflows, lack of content
> writing uniformity, none or not ideal source-to-doc
> translation (e.g. Doxygen issues). 

Exactly.  And now you're proposing to increase the diversity... unless
you mean to rewrite all the existing docs.

> Remembering long way of documenting Boost.Geometry, I'm not 100% happy
> with the results.  Perhaps it's only my opinion.  I'm not going to
> ignite any fermentation. I'm just curious, if boostdoc/quickbook is
> really superior to, say, reStructuredText + Sphinx tandem.

The differences run deep.  If it was a totally clear cut win for ReST,
I'd have pushed for its exclusive adoption years ago.

- quickbook is an extensible programming language; ReST is explicitly
  trying *not* to be programmable

- quickbook generates boostbook, which can represent rich semantic
  information.  ReST can't very cleanly express arbitrary semantic or
  visual markup (bold-italic anyone?)

- quickbook is maintained by Boosters when they have the time, docbook
  is maintained externally

- quickbook takes a long time to compile, docbook is Python

- quickbook is not really used outside of Boost; docbook is used by
  manymanymany

- there's no usable Emacs editing mode for quickbook; there is for ReST.

...

Any ideas about how to address these issues?

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com