Documenting Python code.

Discussion in 'Python' started by Isaac Rodriguez, May 3, 2005.

  1. 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
     
    Isaac Rodriguez, May 3, 2005
    #1
    1. Advertising

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

    Michele Simionato
     
    Michele Simionato, May 3, 2005
    #2
    1. Advertising

  3. 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/
     
    George Yoshida, May 3, 2005
    #3
  4. 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
     
    =?iso-8859-1?q?S=E9bastien_Boisg=E9rault?=, May 3, 2005
    #4
  5. 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.
     
    Leif K-Brooks, May 3, 2005
    #5
  6. 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>
     
    Fredrik Lundh, May 5, 2005
    #6
    1. Advertising

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

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Replies:
    0
    Views:
    627
  2. Andre Kostur

    Re: Documenting code in c++

    Andre Kostur, Jun 30, 2003, in forum: C++
    Replies:
    0
    Views:
    392
    Andre Kostur
    Jun 30, 2003
  3. Replies:
    5
    Views:
    420
    Cedric LEMAIRE
    Sep 3, 2003
  4. Jeff Rodriguez

    Documenting C Code

    Jeff Rodriguez, Nov 18, 2003, in forum: C Programming
    Replies:
    17
    Views:
    929
    CBFalconer
    Nov 20, 2003
  5. Rony
    Replies:
    2
    Views:
    584
Loading...

Share This Page