Best way to document Python code...

[Adonis Vargas]

Scott Huey wrote:
> I am working on a Python module and I would like to prepare some API
> documentaiton. I managed to find epydoc after some searching online.
> 
> Is there a standard way to document the API for Python modules? Is
> epydoc the best way to go if there is no standard? Are there other ways
> to document a Python API?
> 
> Thanks,
> 
> Scott Huey
> 

The "standard" is to use docstrings

i.e.,

class MyModule:
     """
     This module does something
     """

     def someMethod(self):
     """
     This method does something, accepts args/returns value etc.
     """

Then one way to view the docstrings is to start a python shell, import 
your module, and do help(MyModule)

i.e.,

module: mymodule.py
class: MyModule

do in the shell:

import mymodule
help(mymodule.MyModule)

Then Python will generate a quick help interface for your module. I 
suspect epydoc uses docstrings but I *may* be wrong, since I have never 
used epydoc. But a quick look at pydoc (not to be confused with epydoc) 
which is part of the standard library allows you to generate 
documentation in HTML format, and/or serve it over web with its built-in 
HTTP server.

pydoc: http://docs.python.org/lib/module-pydoc.html

Hope this helps.

Adonis