Documentation

[Jan Danielsson]

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.

[Jason Drew]

The standard pydoc module is very useful. A simple example of how you
could use it:

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)

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.

[Paul McGuire]

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