Re: Sphinx integration

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

> On 05/10/11 11:55, Paul A. Bristow wrote:
>> Dave Abrahams wrote: 
>
>
>> 2  The results of Pierre Talbot, the GSoC student that I mentored
>> this summer (and put the hard word on him to write the docs using
>> these tools - including switching on a Doxygen switch that nags you 
>> if you fail to document every class, function etc).
>> 
>> For his Quickbook toolchain generated docs see
>> 
>> https://svn.boost.org/svn/boost/sandbox/SOC/2011/checks/libs/checks/doc/html/index.html
>>
>> [...]
>> You can compare what you get by looking at the 'Checks Reference
>> section' and the 'Class list' and choosing a class to find what they
>> might do for you.
>
> 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?

>
> I still vote for Boost.Asio docs as an examplar.

+1

Please view http://warpspire.com/talks/documentation/

> First page displays clearly indicates what user can expect form the
> documentation:
>
> http://www.boost.org/doc/libs/1_47_0/doc/html/boost_asio.html
>
> Reference displays all elements according to physical and logical
> structure of the software components:
>
> http://www.boost.org/doc/libs/1_47_0/doc/html/boost_asio/reference.html
>
> A single class page gives overview description, members summary
> and usage example - no more-and-too-detailed information presented:
>
> http://www.boost.org/doc/libs/1_47_0/doc/html/boost_asio/reference/streambuf.html
>
> A class member page follows exactly the same convention as above:
>
> http://www.boost.org/doc/libs/1_47_0/doc/html/boost_asio/reference/basic_streambuf/size.html
>
> If it is a template, then corresponding type requirements are linked.
>
> Every page of a reference is structured and formatted according to the
> same rules. This makes it extremely easy to get familiar with
> documentation. User needs to visit two pages at most to learn how to
> read the documentation.
>
> IMO, it would be beneficial if every library in Boost follows consistent
> convention, so switching from library X to Y does not
> change the way user navigates and reads the documentation
> Think of MSDN for Boost.
>
> The quality of discoverability does not only applies to API of software
> but also to technical documentation, IMO.

+1

>
>> Other 'concepts' like Concepts that are not part of the C++ language
>> could be accommodated by convention using the \note or \remark
>> comments?
>
> IMO, it's not enough.
>
>> Finally do not forget that you can get an *index* of all this, for
>> zero or modest effort. How many times have I forgotten what a Boost
>> function or macro is called or does?  An index would have saved so
>> much Googling (and bad language and blood pressure elevation!)
>
> It is a nice feature, but IMO it is rated not higher than 5-6
> in from 1 to 10. Reading documentation is tangent and parallel to
> learning about a library. I start using index once I passed
> beginner (and even intermediate) level of documentation reading.

+1

>> Now I'm not pretending that all this comes for free - it does mean a
>> lot more work for the author (and it clutters the source code),
>
> The code clutter is pointed as major drawback of Doxygen use.

+1

>> but IMO the results are vastly more useful to the *user* and well worth
>> the effort.
>
> My own manifest is:
> - Standalone native Doxygen doc is useful as API reference.
> - Standalone native Doxygen doc is not useful as a handbook-like
> documentation.
> - Boost documentation is not only API reference, but a handbook.

+10

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