Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Dave Abrahams (dave_at_[hidden])
Date: 2011-10-07 20:04:26

on Fri Oct 07 2011, Mateusz Loskot <mateusz-AT-loskot.net> wrote:

> On 07/10/11 02:51, Dave Abrahams wrote:
>> on Thu Oct 06 2011, Mateusz Loskot<mateusz-AT-loskot.net>  wrote:
>
>>> In my opinion, docs formatted/presented like this
>>>
>>> https://svn.boost.org/svn/boost/sandbox/SOC/2011/checks/libs/checks/doc/html/boost/checks/luhn_algorithm.html
>>>
>>> will put most readers off. Looks terrible, if I may express my
>>> opinion.
>>>
>>> Format and layout of class documentation in the standalone version
>>> is way better.
>>
>> Which one is that?
>
> This is what Paul and myself call standalone Doxygen documentation
>
> https://svn.boost.org/svn/boost/sandbox/SOC/2011/checks/libs/checks/doc/doxygen/html/index.html
>
> IOW, it's native Doxygen HTML output.
>
>>> I still vote for Boost.Asio docs as an examplar.
>>
>> +1
>>
>> Please view http://warpspire.com/talks/documentation/
>
> Wow! If I have known this presentation, it would have saved
> me a lot of typing. Awesome!

Yeah, we should refer to it from whatever Boost page we have on
documentation.

> The very first question that came to my mind, what is wrong with C++?
> Why documentations in scripting world can be clean, friendly,
> usable and pretty?

I don't think this is a C++-vs-scripting thing.  However, we generally
have a lot more to document and hold ourselves to a much higher standard
of rigor than most people writing in scripting languages.

> Looking at slides 30-37, I'm wondering...why Boost documentation
> looks and feels more like a scientific paper than a handbook.
> The handbooks are for mortals. The scientific paper are not.
> The Boost is developed by immortals, so let them use scientific paper.
> The Boost is for use mostly by mortals who need handbook, but not
> scientific paper, about Boost.
>
> If Boost documentation (and website) aims the slides 30-37, it will be
> a rockstar documentation.
>
> Is it possible at all?

Yes, it's possible.  Are you familiar with
https://svn.boost.org/trac/boost/wiki/ImprovingBoostDocs#Objectives?
That could be revived.  Matias Capeletto was the driving force, IIRC.

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