473,898 Members | 2,481 Online
Bytes | Software Development & Data Engineering Community
+ Post

Home Posts Topics Members FAQ

Best way to document Python code...

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

Jan 22 '07 #1
9 5626
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
Jan 22 '07 #2
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
Jan 22 '07 #3
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

Jan 22 '07 #4
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!
http://www.yahoo.com.ar/respuestas

Jan 22 '07 #5
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 <st****@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.

Jan 22 '07 #6
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 <st****@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.

Jan 23 '07 #7

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

- Paddy.

Jan 23 '07 #8
On 2007-01-22, be************@ lycos.com <be************ @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

Jan 23 '07 #9
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.
Jan 24 '07 #10

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

36
2784
by: ChinStrap | last post by:
When not using the interactive prompt, what are you using? I keep hearing everyone say Emacs, but I can't understand it at all. I keep trying to learn and understand why so many seem to like it because I can't understand customization even without going through a hundred menus that might contain the thing I am looking for (or I could go learn another language just to customize!). Personally I like SciTE, it has everything I think a...
2
1702
by: JR | last post by:
Hi. I have a CGI script that will need to call itself an unknown number of times, to add rows, run queries, etc. At the bottom of the output that is produced by the script, there are four buttons. I need one of the buttons to simply be a back button. I have this button working fine. I need the second and fourth buttons to point to the current CGI script, but I need the third button to point to a different CGI script. I need the...
1
1685
by: JackPhil | last post by:
I searched in the python-mode.el, sf.net, python.org, and found nothing Best regards
136
9500
by: Matt Kruse | last post by:
http://www.JavascriptToolbox.com/bestpractices/ I started writing this up as a guide for some people who were looking for general tips on how to do things the 'right way' with Javascript. Their code was littered with document.all and eval, for example, and I wanted to create a practical list of best practices that they could easily put to use. The above URL is version 1.0 (draft) that resulted. IMO, it is not a replacement for the FAQ,...
6
5389
by: metaperl | last post by:
Hello, I am responsible for converting 30 loosey-goosey Perl scripts into 30 well-documented easy to understand and use Python scripts. No one has said anything in particular about how this should be done, but the end product should be "professional" looking. So, I'm looking for some books and suggestions which will help me write high-quality scripts. I know about object-oriented programming and application configuration and have spent...
42
2468
by: Hakusa | last post by:
Recently I've had some problems with PythonWin when I switched to Py2.5, tooka long hiatus, and came back. So now I'm without my god sent helper, and I'm looking for a cool replacement, or some advocation to reinstall/setup PyWin. But the Python website's list is irrefutably long. It would take a month or two to test all of those products. So I'm looking for experienced advocates. What's your favorite IDE? What do you like about it? It...
5
2491
by: kyosohma | last post by:
Hi all, I am attempting to create an XML document dynamically with Python. It needs the following format: <zAppointments reminder="15"> <appointment> <begin>1179775800</begin> <duration>1800</duration> </appointment>
5
2889
by: Frank Millman | last post by:
Hi all This is not strictly a Python question, but as I am writing in Python, and as I know there are some XML gurus on this list, I hope it is appropriate here. XML-schemas are used to define the structure of an xml document, and to validate that a particular document conforms to the schema. They can also be used to transform the document, by filling in missing attributes with default values.
10
3943
by: Brendan Miller | last post by:
What would heavy python unit testers say is the best framework? I've seen a few mentions that maybe the built in unittest framework isn't that great. I've heard a couple of good things about py.test and nose. Are there other options? Is there any kind of concensus about the best, or at least how they stack up to each other? Brendan
0
9993
marktang
by: marktang | last post by:
ONU (Optical Network Unit) is one of the key components for providing high-speed Internet services. Its primary function is to act as an endpoint device located at the user's premises. However, people are often confused as to whether an ONU can Work As a Router. In this blog post, we’ll explore What is ONU, What Is Router, ONU & Router’s main usage, and What is the difference between ONU and Router. Let’s take a closer look ! Part I. Meaning of...
0
9842
by: Hystou | last post by:
Most computers default to English, but sometimes we require a different language, especially when relocating. Forgot to request a specific language before your computer shipped? No problem! You can effortlessly switch the default language on Windows 10 without reinstalling. I'll walk you through it. First, let's disable language synchronization. With a Microsoft account, language settings sync across devices. To prevent any complications,...
0
11265
Oralloy
by: Oralloy | last post by:
Hello folks, I am unable to find appropriate documentation on the type promotion of bit-fields when using the generalised comparison operator "<=>". The problem is that using the GNU compilers, it seems that the internal comparison operator "<=>" tries to promote arguments from unsigned to signed. This is as boiled down as I can make it. Here is my compilation command: g++-12 -std=c++20 -Wnarrowing bit_field.cpp Here is the code in...
1
10954
by: Hystou | last post by:
Overview: Windows 11 and 10 have less user interface control over operating system update behaviour than previous versions of Windows. In Windows 11 and 10, there is no way to turn off the Windows Update option using the Control Panel or Settings app; it automatically checks for updates and installs any it finds, whether you like it or not. For most users, this new feature is actually very convenient. If you want to control the update process,...
0
9662
agi2029
by: agi2029 | last post by:
Let's talk about the concept of autonomous AI software engineers and no-code agents. These AIs are designed to manage the entire lifecycle of a software development project—planning, coding, testing, and deployment—without human intervention. Imagine an AI that can take a project description, break it down, write the code, debug it, and then launch it, all on its own.... Now, this would greatly impact the work of software developers. The idea...
1
8036
isladogs
by: isladogs | last post by:
The next Access Europe User Group meeting will be on Wednesday 1 May 2024 starting at 18:00 UK time (6PM UTC+1) and finishing by 19:30 (7.30PM). In this session, we are pleased to welcome a new presenter, Adolph Dupré who will be discussing some powerful techniques for using class modules. He will explain when you may want to use classes instead of User Defined Types (UDT). For example, to manage the data in unbound forms. Adolph will...
0
7191
by: conductexam | last post by:
I have .net C# application in which I am extracting data from word file and save it in database particularly. To store word all data as it is I am converting the whole word file firstly in HTML and then checking html paragraph one by one. At the time of converting from word file to html my equations which are in the word document file was convert into image. Globals.ThisAddIn.Application.ActiveDocument.Select();...
0
5882
by: TSSRALBI | last post by:
Hello I'm a network technician in training and I need your help. I am currently learning how to create and manage the different types of VPNs and I have a question about LAN-to-LAN VPNs. The last exercise I practiced was to create a LAN-to-LAN VPN between two Pfsense firewalls, by using IPSEC protocols. I succeeded, with both firewalls in the same network. But I'm wondering if it's possible to do the same thing, with 2 Pfsense firewalls...
3
3308
bsmnconsultancy
by: bsmnconsultancy | last post by:
In today's digital era, a well-designed website is crucial for businesses looking to succeed. Whether you're a small business owner or a large corporation in Toronto, having a strong online presence can significantly impact your brand's success. BSMN Consultancy, a leader in Website Development in Toronto offers valuable insights into creating effective websites that not only look great but also perform exceptionally well. In this comprehensive...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.