Best way to document Python code...

**Adonis Vargas** · Jan 22 '07, 08:45 PM

Re: Best way to document Python code...

Scott Huey wrote:

I am working on a Python module and I would like to prepare some API
documentaiton. I managed to find epydoc after some searching online.
>
Is there a standard way to document the API for Python modules? Is
epydoc the best way to go if there is no standard? Are there other ways
to document a Python API?
>
Thanks,
>
Scott Huey
>

The "standard" is to use docstrings

i.e.,

class MyModule:
"""
This module does something
"""

def someMethod(self ):
"""
This method does something, accepts args/returns value etc.
"""

Then one way to view the docstrings is to start a python shell, import
your module, and do help(MyModule)

i.e.,

module: mymodule.py
class: MyModule

do in the shell:

import mymodule
help(mymodule.M yModule)

Then Python will generate a quick help interface for your module. I
suspect epydoc uses docstrings but I *may* be wrong, since I have never
used epydoc. But a quick look at pydoc (not to be confused with epydoc)
which is part of the standard library allows you to generate
documentation in HTML format, and/or serve it over web with its built-in
HTTP server.

pydoc: http://docs.python.org/lib/module-pydoc.html

Hope this helps.

Adonis

**Boris Ozegovic** · Jan 22 '07, 08:55 PM

Re: Best way to document Python code...

Adonis Vargas wrote:

Then Python will generate a quick help interface for your module. I

Hi

Does Python has API just like in Java, for example
http://java.sun.com/j2se/1.5.0/docs/...s-noframe.html ctrl-f and
than click on class you are searching for, and finally you get clean list
of all fields and methods. Where can I find similar in Python, for
example, if I would like to see which methods list/dictionary has.

--
"kad ima¹ 7 godina glup si ko kurac, sve je predobro: autiæi i bageri u
kvartu.. to je ¾ivot"
Drito Konj

**bearophileHUGS@lycos.com** · Jan 22 '07, 09:15 PM

Re: Best way to document Python code...

Boris Ozegovic:

Does Python has API just like in Java, for example
http://java.sun.com/j2se/1.5.0/docs/...s-noframe.html ctrl-f and
than click on class you are searching for, and finally you get clean list
of all fields and methods. Where can I find similar in Python, for
example, if I would like to see which methods list/dictionary has.

You can do that from the shell, with help(name) or dir(name), where
name can be a class, object, most things.

Bye,
bearophile

**Gabriel Genellina** · Jan 22 '07, 09:25 PM

Re: Best way to document Python code...

At Monday 22/1/2007 17:48, Boris Ozegovic wrote:

>Does Python has API just like in Java, for example
>http://java.sun.com/j2se/1.5.0/docs/...s-noframe.html ctrl-f and
>than click on class you are searching for, and finally you get clean list
>of all fields and methods. Where can I find similar in Python, for
>example, if I would like to see which methods list/dictionary has.

Python 2.4.2 (#67, Sep 28 2005, 12:41:11) [MSC v.1310 32 bit (Intel)] on win32
Type "help", "copyright" , "credits" or "license" for more information.
pyhelp(dict)
Help on class dict in module __builtin__:

class dict(object)
| dict() -new empty dictionary.
| dict(mapping) -new dictionary initialized from a mapping object's
| (key, value) pairs.
| dict(seq) -new dictionary initialized as if via:
| d = {}
| for k, v in seq:
| d[k] = v
| dict(**kwargs) -new dictionary initialized with the name=value pairs
| in the keyword argument list. For example: dict(one=1, two=2)
|
| Methods defined here:
|
| __cmp__(...)
| x.__cmp__(y) <==cmp(x,y)
|
| __contains__(.. .)

You should skip at first magic __methods__. You can use help() with
any object, or language keyword: help("if")

pyimport math
pyhelp(math)
Help on built-in module math:

NAME
math

FILE
(built-in)

DESCRIPTION
This module is always available. It provides access to the
mathematical functions defined by the C standard.

FUNCTIONS
acos(...)
acos(x)

Return the arc cosine (measured in radians) of x.
[...]

--
Gabriel Genellina
Softlab SRL

_______________ _______________ _______________ _____
Preguntá. Respondé. Descubrí.
Todo lo que querías saber, y lo que ni imaginabas,
está en Yahoo! Respuestas (Beta).
¡Probalo ya!

Yahoo

http://www.yahoo.com.ar/respuestas

**Stuart D. Gathman** · Jan 22 '07, 10:45 PM

Re: Best way to document Python code...

On Mon, 22 Jan 2007 20:40:57 +0000, Adonis Vargas wrote:

But a quick look at pydoc (not to be confused with epydoc)
which is part of the standard library allows you to generate
documentation in HTML format, and/or serve it over web with its built-in
HTTP server.
>
pydoc: http://docs.python.org/lib/module-pydoc.html
>
Hope this helps.
>
Adonis

The HTML generated by pydoc doesn't link to standard modules properly.
They are generated as relative links. So it can't be used without
modification for generating docs for a web page about a python package.

I'm struggling with the same issue. Coding Python is so much easier than
Java. However documenting Java is so much easier than Python. Just
include doc comments, run javadoc, and voila!

--
Stuart D. Gathman <stuart@bmsi.co m>
Business Management Systems Inc. Phone: 703 591-0911 Fax: 703 591-6154
"Confutatis maledictis, flamis acribus addictis" - background song for
a Microsoft sponsored "Where do you want to go from here?" commercial.

**Stuart D. Gathman** · Jan 23 '07, 12:55 AM

Re: Best way to document Python code...

On Mon, 22 Jan 2007 17:35:18 -0500, Stuart D. Gathman wrote:

The HTML generated by pydoc doesn't link to standard modules properly.
They are generated as relative links. So it can't be used without
modification for generating docs for a web page about a python package.
>
I'm struggling with the same issue. Coding Python is so much easier than
Java. However documenting Java is so much easier than Python. Just
include doc comments, run javadoc, and voila!

Wow! I just tried epydoc, and it is every bit as easy as javadoc and
with similar output. Too bad it isn't standard. But the comments and
docstrings it parses work fine with pydoc also.

--
Stuart D. Gathman <stuart@bmsi.co m>
Business Management Systems Inc. Phone: 703 591-0911 Fax: 703 591-6154
"Confutatis maledictis, flamis acribus addictis" - background song for
a Microsoft sponsored "Where do you want to go from here?" commercial.

**Paddy** · Jan 23 '07, 02:35 AM

Re: Best way to document Python code...

Scott Huey wrote:

I am working on a Python module and I would like to prepare some API
documentaiton. I managed to find epydoc after some searching online.
>
Is there a standard way to document the API for Python modules? Is
epydoc the best way to go if there is no standard? Are there other ways
to document a Python API?
>
Thanks,
>
Scott Huey

To add to the other replies: try adding a few doctests to your
docstrings. They can help show typical use cases even if you don't use
them for 'testing' - and you can automatically keep the use cases
up-to-date.

doctest - Wikipedia

http://en.wikipedia.org/wiki/Doctest

- Paddy.

**Neil Cerutti** · Jan 23 '07, 05:35 PM

Re: Best way to document Python code...

On 2007-01-22, bearophileHUGS@ lycos.com <bearophileHUGS @lycos.comwrote :

Boris Ozegovic:

>Does Python has API just like in Java, for example
>http://java.sun.com/j2se/1.5.0/docs/...s-noframe.html ctrl-f and
>than click on class you are searching for, and finally you get clean list
>of all fields and methods. Where can I find similar in Python, for
>example, if I would like to see which methods list/dictionary has.

>
You can do that from the shell, with help(name) or dir(name),
where name can be a class, object, most things.

It is OK for a lark, but sadly dir is not suitable enough. You do
need to refer to the documentation off-line or you'll miss vital
entries. It won't hurt to read effbot.org, either, as I keep
finding out.

Also check out the interactive help system. If you've got the
html versions of the docs installed, it functions somewhat like
perldoc. Type help() at the interactive prompt to get started.

--
Neil Cerutti
Will the last person to leave please see that the perpetual light is
extinguished --sign at New England church

--
Posted via a free Usenet account from http://www.teranews.com

**Nick Vatamaniuc** · Jan 24 '07, 10:25 PM

Re: Best way to document Python code...

Epydoc is the way to go. You can even choose between various formating
standards (including javadoc ) and customize the output using CSS.

On Jan 22, 7:51 pm, "Stuart D. Gathman" <stu...@bmsi.co mwrote:

On Mon, 22 Jan 2007 17:35:18 -0500, Stuart D. Gathman wrote:

The HTML generated by pydoc doesn't link to standard modules properly.
They are generated as relative links. So it can't be used without
modification for generating docs for a web page about a python package.

>

I'm struggling with the same issue. Coding Python is so much easier than
Java. However documenting Java is so much easier than Python. Just
include doc comments, run javadoc, and voila!Wow! I just tried epydoc, and it is every bit as easy as javadoc and

with similar output. Too bad it isn't standard. But the comments and
docstrings it parses work fine with pydoc also.
>
--
Stuart D. Gathman <stu...@bmsi.co m>
Business Management Systems Inc. Phone: 703 591-0911 Fax: 703 591-6154
"Confutatis maledictis, flamis acribus addictis" - background song for
a Microsoft sponsored "Where do you want to go from here?" commercial.

Best way to document Python code...

Best way to document Python code...

Comment

Comment

Comment

Comment

Comment

Comment

Comment

Comment

Comment