Automatic Documentation Tools?

[Tony J Ibbs (Tibs)]

Terry Hancock <hancock at earthlink.net> writes:
> I've seen a number of automatically generated documentation
> on the web for C/C++ source code.  Is there anything like
> this for Python?  I've taken over documenting a piece of
> code, and it would be nice to at list have a list of classes,
> attributes, and methods from which to work.  Seems like it
> ought to be automateable, but I don't know the fastest way
> to do it.

Well, there are two answers to that.


Answer number 1: the technology of the past

There are several tools out there that look through Python code for doc
strings, etc., and interpret them using StructuredText conventions,
including at least:
* Crystal (http://www.btinternet.com/~tratt/comp/python/crystal/)
* HappyDoc (http://happydoc.sourceforge.net/)
* pythondoc (http://starship.python.net/crew/danilo/pythondoc/)
  (the successor to gendoc)

For a slightly different approach, see Ka-Ping Yee's htmldoc, near the
end of the page at http://www.lfw.org/python/ - this requires
downloading two files. If it weren't for answer number 2 below, this
might be the nearest to what you want.


Answer number 2: the technology yet to come

Attempts are being made to produce "standard" tools for doing just this
task. To find out exactly what is going on, you need to follow the
Doc-SIG (http://www.python.org/sigs/doc-sig/ - but note that the
description of current state at that page is a bit out-of-date).

Here's a summary:

* Ka-Ping Yee has just (literally in the last few days) released pydoc
("a documentation generator that works from the command line, in the
Python interpreter, and as a web server in the background"). This can be
found at the very end of his page http://www.lfw.org/python/, and is
almost certainly what you *actually* want, at least for now. Be aware
that it is new software, and still being improooooved (although that
doesn't stop it from being wonderful as it stands right now, but it does
mean you should check back for updates of the source code periodically).
Unofficially ('cos I don't get to make the decision!) I would expect
this to be in Python 2.1. Note that it definitely works with 1.5.2,
though, 'cos I've tried it. Oh, and it actually *includes* htmldoc (see
answer number 1 above), so you can't lose.

* Somewhere in the aether is the tool I'm working on, which will do the
complementary job of parsing (a variant of) StructuredText from Python
docstrings so that they can be emitted as HTML, XML, TeX or whatever.
Unfortunately, that's still vapourware, at least for this week, and
probably for next week as well.


Hope that helps.
Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)