[Buildbot-devel] build properties ...

[Brian Warner]

From: Alexander Lorenz <lorenz at testingtech.de>
Subject: [Buildbot-devel] build properties ...
> ... are also not documented in the manual.

Please take a look in the 0.7.3 user's manual[1] at section 6.1.4.5 entitled
"Build Properties"[2] and tell me what needs to be changed. I neglected to
put a CVS-HEAD version of the user's manual up online before releasing 0.7.3,
so until the release was made, the only way to see the documentation on the
new features was to get a checkout of the HEAD code from CVS/Darcs/Arch. My
apologies.

> so e.g. forementioned parameter "allowForce" was absolutely new to me.

FWIW, allowForce= is an argument to the Waterfall display, not a build
property. I added documentation for it to the user's manual section on the
Waterfall display[3].

> it's seem to be like this with a number of features ... in order to be 
> able to evaluate the full potential of buildbot, so far you have to not 
> only read the manual but also browse all python source files for pydoc 
> commentaries.
> this should be changed and all feature be documented in the manual.

I have to agree. I'm still trying to figure out the best way to do some form
of "literate programming" in python. Docstrings seem to be an appropriate
place to put descriptions of functions and their arguments: by placing them
inside the function where they are actually used, they stand the best chance
of remaining accurate and up-to-date. However, to actually read the
docstrings you have to either run pydoc[4], or look at the online API
reference[5] in the section that covers the Waterfall class [6], both of
which are a bit of a drag to use, and it's nontrivial to figure out what
class+method to be looking at in the first place.. it's like trying to find
the dentist's office by looking at a blueprint of the of the building: too
much detail to distinguish the doors that are meant for customers from the
air-conditioning ducts.

So the User's Manual is the best place for users to find that sort of
information (both the guide that says what classes are interesting to look
at, and the description of the arguments to those classes), but the user's
manual is kept in a separate document than the source code. Therefore it is
more time-consuming to keep in sync with the code, and is thus more
vulnerable to drift than the docstrings.

I don't know of a good solution or tool to manage this process. My intention
is to have the user's manual be the primary place where users can learn how
to use the buildbot, but the user's manual is a lot younger than the rest of
the code, so there are places where the primary documentation is still in the
docstrings. And even after e.g. Waterfall has been documented in
buildbot.texinfo, I'm loathe to delete the docstrings, because that's where a
pydoc-using python programmer (as opposed to the User's Manual-using, er,
user) would think to look for them. Really I want a way to have the
docstrings get interpolated into the user's manual in the right page, so I
only have to maintain one copy of those docs.

Any ideas?

cheers,
 -Brian



[1]: http://buildbot.sourceforge.net/manual-0.7.3.html
[2]: http://buildbot.sourceforge.net/manual-0.7.3.html#Build-Properties
[3]: http://buildbot.sourceforge.net/manual-0.7.3.html#HTML-Waterfall
[4]: e.g. try running 'pydoc buildbot.status.html.Waterfall.__init__' . I'm
     surprised that 'pydoc ...Waterfall' doesn't work.. that seems like
     broken behavior in pydoc, to me.
[5]: http://buildbot.sourceforge.net/API-0.7.3/index.html
[6]: http://buildbot.sourceforge.net/API-0.7.3/buildbot.status.html.Waterfall-class.html