Documenting Python code.

[Isaac Rodriguez]

Hi,

Are there any standarized ways of documenting Python code? When I check the
__doc__ attribute of the standard modules, the results are kind of plain. Is
everyone using this style?

Since Python is a very powerful language parsing strings, replacing
expressions, and processing XML, I was wondering if people documents the
code using constructs similar to JavaDoc and then use some functions to
display the documentation with a little bit more of structure.

Python is a dynamically typed language, which makes me think of the
importance of documenting not only the purpose of a particular function or
class method, but also what requirements should be met by the objects passed
as parameters, what will the function return, and what type of erros can
happen. I don't see any of this information in the __doc__ attributes, so I
was wondering if people is using some other way to document their code.

If there is no standard way to do this inside the Python community, does
anyone feels there is a need for standarizing it?

Thanks,

--
Isaac Rodriguez
SWE Autodesk.
========================================
There are 10 types of people.
Those who undertand binary, and those who don't

 

[Michele Simionato]

I would say reStructuredText is the preferred format
for documenting Python code. Google is your friend.

Michele Simionato

 

[George Yoshida]

> Python is a dynamically typed language, which makes me think of the
> importance of documenting not only the purpose of a particular function or
> class method, but also what requirements should be met by the objects passed
> as parameters, what will the function return, and what type of erros can
> happen. I don't see any of this information in the __doc__ attributes, so I
> was wondering if people is using some other way to document their code.

I guess you're talking about something like literate programming.
If so, doctest module may be useful for that purpose. Doctest can also
be used as a unittest.

 

[=?iso-8859-1?q?S=E9bastien_Boisg=E9rault?=]

Have a look at Epydoc (http://epydoc.sourceforge.net/), a documentation
system
that generates HTML and PDF docs. Plain text, Javadoc,
ReStructuredText,
and Epytext docstrings are handled gracefully.

ReStructuredText (or a suitable subset of RST) is probably the best
choice IMHO.

SB

 

[Leif K-Brooks]

Are there any standarized ways of documenting Python code? When I check the
__doc__ attribute of the standard modules, the results are kind of plain. Is
everyone using this style?

See <http://epydoc.sourceforge.net/>. Epydoc has a simple language for
documentation that can markup type information for paramaters and other
stuff like that.

 

[Fredrik Lundh]

Since Python is a very powerful language parsing strings, replacing
expressions, and processing XML, I was wondering if people documents the
code using constructs similar to JavaDoc

if you want something very similar to JavaDoc, you can use PythonDoc:

http://effbot.org/zone/pythondoc.htm

</F>