On Jan 23, 2006, at 4:20 PM, Jeff Watkins wrote:
On 23 Jan, 2006, at 6:06 pm, Bob Ippolito wrote:
Hacking docutils isn't all that hard.
I would like to suggest that we choose something that doesn't
require hacking. If it doesn't work easily, it won't get used.
Documentation and tests (I'm guilty on this) is usually the last
thing to get done because the fancy tools need hand-holding.
Let's pick something that *already* works and run with it.
Nothing already works. I've been doing Python for a few years now,
and all the mature docs-from-source tools suck hard. The
signal:noise ratio is like 0.001, and/or the docstring markup is
stupid. I do not want my source code to be <b>@ugly</b>. It's WAY
more efficient for me to grep the source and read the docs in source
form than to navigate a 2000 file three-frame HTML document tree.
Docutils comes very close to being good as an external document tool,
but it needs a couple lines of domain-specific roles in order to make
cross-referencing work well. That's a pretty big barrier to entry,
but the markup is excellent and the output is flexible. For
MochiKit, it was more than worth writing forty lines of code or so to
make that happen (most of the code revolves around just finding the
doc files, not the roles).
What's needed in this case is a doc-from-source tool, which pretty
much leaves just Pudge and PythonDoc as decent options. Pudge has
docutils behind it, but is nascent. PythonDoc is a bit more mature,
but it requires inline HTML for any markup that isn't represented by
the PythonDoc @tags (e.g. emphasis, tables, etc.).
For an example of what docutils markup looks like in source code, you
could take a look at some of simplejson's source:
http://svn.red-bean.com/bob/simplejson/trunk/simplejson/encoder.py
and the Pudge output:
http://svn.red-bean.com/bob/simplejson/trunk/docs/class-
simplejson.JSONEncoder.html
http://svn.red-bean.com/bob/simplejson/trunk/docs/simplejson/
encoder.py.html?f=63&l=277#63
For me, it was well worth a little hacking to make sure my (a) source
wasn't fugly (b) the output is navigable.
Compare this index page to TurboGears, for example:
http://svn.red-bean.com/bob/simplejson/trunk/docs/index.html
In this case, Pudge puts all the information you need in one place,
**skipping over irrelevant modules, like the tests**, instead of just
a long unfiltered list of modules with mostly meaningless comments
(when there are comments). API documentation should absolutely not
include tests or private APIs that the user doesn't need to know
about. That's what the source is for.
I had to make some slight changes to Pudge in order to make that
happen, but nothing big, and I didn't spend very long on it. I'm not
saying Pudge is painless, because it's not, but at least the output
is useful.
-bob
