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 9 5593
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.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
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
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
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
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.com>
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.
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.com>
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.
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.
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
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.comwrote:
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.com>
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.
This thread has been closed and replies have been disabled. Please start a new discussion. Similar topics
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...
|
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...
|
by: JackPhil |
last post by:
I searched in the python-mode.el, sf.net, python.org, and found nothing
Best regards
|
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...
|
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...
|
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...
|
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>...
|
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...
|
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...
|
by: emmanuelkatto |
last post by:
Hi All, I am Emmanuel katto from Uganda. I want to ask what challenges you've faced while migrating a website to cloud.
Please let me know.
Thanks!
Emmanuel
|
by: BarryA |
last post by:
What are the essential steps and strategies outlined in the Data Structures and Algorithms (DSA) roadmap for aspiring data scientists? How can individuals effectively utilize this roadmap to progress...
|
by: nemocccc |
last post by:
hello, everyone, I want to develop a software for my android phone for daily needs, any suggestions?
|
by: Hystou |
last post by:
There are some requirements for setting up RAID:
1. The motherboard and BIOS support RAID configuration.
2. The motherboard has 2 or more available SATA protocol SSD/HDD slots (including MSATA, M.2...
|
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,...
|
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,...
|
by: tracyyun |
last post by:
Dear forum friends,
With the development of smart home technology, a variety of wireless communication protocols have appeared on the market, such as Zigbee, Z-Wave, Wi-Fi, Bluetooth, etc. Each...
|
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,...
|
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...
| |