Documenting Python code.

  • Thread starter Isaac Rodriguez
  • Start date
I

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
 
M

Michele Simionato

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

Michele Simionato
 
G

George Yoshida

Isaac said:
> 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
 
L

Leif K-Brooks

Isaac said:
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.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,733
Messages
2,569,440
Members
44,830
Latest member
ZADIva7383

Latest Threads

Top