Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Dave Abrahams (dave_at_[hidden])
Date: 2011-10-05 14:42:55

on Wed Oct 05 2011, "Paul A. Bristow" <pbristow-AT-hetp.u-net.com> wrote:

>> -----Original Message-----
>
>> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
>> Dave Abrahams
>> Sent: Tuesday, October 04, 2011 11:35 PM
>> To: boost-docs_at_[hidden]
>> Subject: Re: [Boost-docs] Sphinx integration
>> 
>> > On 04/10/11 18:16, Dave Abrahams wrote:
>> >> on Mon Oct 03 2011, "Paul A. Bristow" <pbristow-AT-hetp.u-net.com> wrote:
>> >
>> >>> Using Doxygen properly and fully, I feel that Boost documentation could be much improved.
>
>> >>> What is wrong is the common delusion that you just chuck your C++
>> >>> code into Doxygen it magically does the whole job : it doesn't - it
>> >>> is a tool for *helping you to document your source code*.
>> >>>
>> >>> You have to do the work - and experience has shown that it is much
>> >>> easier done when you first write the code!
>> >>
>> >> If that is indeed the case, Paul, someone (I'm lookin' at you) needs
>> >> to write a guide to using Doxygen for Boost.  I would definitely try
>> >> to use it next time if someone could show me how to make it really
>> >> work for our docs.
>> >
>> > Paul listed very useful features and directives of Doxygen, but
>> > without explanation how to use them to write rockstar documentation for Boost.
>
> Ah well - as it happens - I have already put some effort into
> recording what I have learned so far from those who know more about
> the toolchain that I do (and still including very many warts and
> wrinkles, and woefully wonky bits),
>
> http://svn.boost.org/svn/boost/sandbox/tools/quick_auto_dox_index/libs/quick_auto_dox_index/doc/quick_auto_dox_index.pdf

*reads*
<exaggeration>
  The need to escape "<" signs in Doxygen comments makes me ill
</exaggeration>

> (you could also build the html version using the jamfile - but who
> wants to build docs?  Updating SVN is a pain because file names keep
> changing).

Yeah, but I think I'd rather read that.  This PDF was produced by FOP,
right?  It's horrible to look at (no offense).

> and I've started on a template that other can used to get started quickly.
>
> https://svn.boost.org/svn/boost/sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.pdf
>
> but did not appear to be used by anyone, so I've taken to trying to
> lead by individual encouragement.

I think leaving people with only a FOP-generated PDF to look at might be
part of the reason.

> To give the flavour of what you get, you might like to look at
>
> 1  My quick and rough translation of Beman's Endian docs into this format.
>
> See
>
> https://svn.boost.org/svn/boost/sandbox/endian_2/libs/endian/doc/html/index.html
>
> or
>
> https://svn.boost.org/svn/boost/sandbox/endian_2/libs/endian/doc/endian.pdf

Those links are broken

> If you look at the class template endian
>
> https://svn.boost.org/svn/boost/sandbox//endian_2/libs/endian/doc/html/boost/endian/endian_endianness_big___id303725.html

As is that one.

> you can see the descriptions of endian functions, for example:
>
> operator T() const;
>
> Returns:  value of endian, the current value stored in *this, converted to value_type.
>
> The ! after /* or // signals to Doxygen that it should associate the comment items with the C++ code.
>
> //! \return value of @c endian, the current value stored in @c *this, converted to @c value_type.
>
> Of course, many of these items are short, and perhaps trivial, but
> they can be longer if appropriate.  At least you can be sure of
> completeness.
>
> AND
>
> 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).

I read all below, but it's "Too Long ; Didn't REPLY"

Anyway, I confess that I find the presentation of Boost's HTML docs
off-putting too.  Maybe I'm just in a grouchy mood this morning.  Before
I can even appreciate what's been done I think I might need to redesign
Boost's stylesheet :(.

> For his Quickbook toolchain generated docs see
>
> https://svn.boost.org/svn/boost/sandbox/SOC/2011/checks/libs/checks/doc/html/index.html
>
> or to see what I call the 'Standalone' Doxygen display is
>
> http://svn.boost.org/svn/boost/sandbox/SOC/2011/checks/libs/checks/doc/doxygen/html/index.html

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