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.

Cheers

-- 
Dean Michael Berris
http://goo.gl/CKCJX