Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Documenting Python code.

Reply
Thread Tools

Documenting Python code.

 
 
Isaac Rodriguez
Guest
Posts: n/a
 
      05-03-2005
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


 
Reply With Quote
 
 
 
 
Michele Simionato
Guest
Posts: n/a
 
      05-03-2005
I would say reStructuredText is the preferred format
for documenting Python code. Google is your friend.

Michele Simionato

 
Reply With Quote
 
 
 
 
George Yoshida
Guest
Posts: n/a
 
      05-03-2005
Isaac Rodriguez wrote:
> 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.

--
george

http://www.dynkin.com/
 
Reply With Quote
 
=?iso-8859-1?q?S=E9bastien_Boisg=E9rault?=
Guest
Posts: n/a
 
      05-03-2005

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

 
Reply With Quote
 
Leif K-Brooks
Guest
Posts: n/a
 
      05-03-2005
Isaac Rodriguez wrote:
> 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.
 
Reply With Quote
 
Fredrik Lundh
Guest
Posts: n/a
 
      05-05-2005
Isaac Rodriguez wrote:

> 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>



 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Help Documenting Python Syntax RJB Python 4 11-10-2010 01:57 PM
documenting formal operational semantics of Python gideon Python 4 03-06-2008 04:11 AM
documenting excepetions in Python dale_bertrand@yahoo.com Python 3 10-19-2007 08:27 PM
Standard way of documenting python code ? Rony Python 2 12-01-2003 09:08 AM
Documenting ASP.NET Tim Almond ASP .Net 1 07-12-2003 03:21 PM



Advertisments