Hello all,

What is the proper way to document a class in Python? I have written
a few python libraries that I would like to document.

I'm doing a lot of this:

class Foo(object):
"""
This is a class which blah, blah, blah... It's features are blah,
blah, blah...
"""

def addStuff(self):
"""
This method does blah, blah, blah...
"""

I'm going to assume that Python has some "official" tool which can be
used to automatically create documentation for a .py-file (like Java
does), but what do I need to do to support it, and how does it work?


--
Kind Regards,
Jan Danielsson
Te audire no possum. Musa sapientum fixa est in aure.

The standard pydoc module is very useful. A simple example of how you
could use it:
[color=blue][color=green][color=darkred]
>>> import pydoc
>>> mymodule = pydoc.importfile(r"C:\My Py\my_foo.py")
>>> html = pydoc.html.page(pydoc.describe(mymodule), pydoc.html.document(mymodule))
>>> open("foo.html", "w").write(html)[/color][/color][/color]

Then you have a nice foo.html document for your module.

The above isn't necessarily the best way to use pydoc though it's
useful for a single-file bunch of classes. The documentation on pydoc
seems pretty sketchy, but reading the pydoc.py file is a good way to
learn how to use it.

Get epydoc from SourceForge (http://epydoc.sourceforge.net/). It will
auto-generate beautiful HTML doc pages for your Python classes, using
the information you have inserted as the doc strings for your classes
and methods. I use it to generate the pyparsing documentation, and it
works very well for me (and I only use about 20% of epydoc's
capabilities).

-- Paul