Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Dean Michael Berris (mikhailberis_at_[hidden])
Date: 2011-09-28 01:20:18

On Tue, Sep 27, 2011 at 11:56 PM, Mateusz Loskot <mateusz_at_[hidden]> 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?

Yes. :)

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

I'm not in the business of saying whether something is superior to
anything else. I just think they're different.

That said, I find writing/reading in ReST is much more enjoyable for
me than doing it in quickbook. Although I started off with quickbook,
I find that it forced me to think more like a programmer than a
writer. ReST is the opposite which is good if the intention is to
write documentation that is meant to be read.

That is IMHO.


Dean Michael Berris

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC