[Buildbot-devel] Documentation (was: WebStatus ponderings)

[Dustin J. Mitchell]

On Thu, Jan 7, 2010 at 2:12 PM, Marcus Lindblom <macke at yar.nu> wrote:
> (Also, I'd love to see some TLC given to the manual's layout/style,
> similar to the new Python docs.)

Agreed -- the current monolithic file is hard to patch, since the
"diff" tells you nothing about the structural impact of the changes.

I've started using sphinx for a few projects[1,2] and been very happy
with it.  The format is easy to edit, without referring to any
description of the format.  The interlinking is natural, and makes it
very easy to organize the content in a way that will guide
contributors to put new content in the right place.  It's also *very*
well suited to Python documentation, with its ability to document
classes, functions, methods, etc. cleanly and in a fashion that
resembles docs.python.org.

I've toyed with spending a weekend converting the manual to Sphinx,
but haven't found the free weekend yet.

Dustin

[1] http://djmitche.github.com/remsh/docs/latest/
[2] http://zmanda.github.com/libzcloud/

-- 
Open Source Storage Engineer
http://www.zmanda.com