Best way to document Python code...

[Scott Huey]

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

 

[Adonis Vargas]

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.MyModule)

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]

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/api/allclasses-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.

 

[bearophileHUGS]

Boris Ozegovic:

Does Python has API just like in Java, for example
http://java.sun.com/j2se/1.5.0/docs/api/allclasses-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]

Does Python has API just like in Java, for example
http://java.sun.com/j2se/1.5.0/docs/api/allclasses-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.
py> help(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")

py> import math
py> help(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!
http://www.yahoo.com.ar/respuestas

 

[Stuart D. Gathman]

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]

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.

 

[Paddy]

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.
http://en.wikipedia.org/wiki/Doctest

- Paddy.

 

[Neil Cerutti]

Boris Ozegovic:

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.

 

[Nick Vatamaniuc]

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