pydoc, best practices, and Data class

[nathan_kent_bullock]

I have a python program that I am trying to generate documentation for.
But in one of my files I have a class called "Data", when pydoc gets to
this class it just barfs. Well more specifically it generates
documentation for only that one class in the file, it ignores the rest
of the classes, plus it doesn't create the standard header, Package
Contents section, Classes section, or anything else. Just wondering if
this is a known bug, I can get around it by naming the class something
else and then just changing all other references to this class.

Second question I have is is there somewhere that gives a good overview
of best practices for documenting code in python. I read something
about ReST (reStructuredText), is this supported by pydoc? Is it
commonly used? I found links to docutils and other things, is pydoc
still the standard method of creating python documentation?

Thanks,
Nathan Bullock

 

[Colin J. Williams]

I have a python program that I am trying to generate documentation for.
But in one of my files I have a class called "Data", when pydoc gets to
this class it just barfs. Well more specifically it generates
documentation for only that one class in the file, it ignores the rest
of the classes, plus it doesn't create the standard header, Package
Contents section, Classes section, or anything else. Just wondering if
this is a known bug, I can get around it by naming the class something
else and then just changing all other references to this class.

Second question I have is is there somewhere that gives a good overview
of best practices for documenting code in python. I read something
about ReST (reStructuredText), is this supported by pydoc? Is it
commonly used? I found links to docutils and other things, is pydoc
still the standard method of creating python documentation?

Thanks,
Nathan Bullock

epydoc is an alternative.

Colin W.