What tools are used to write and generate Python Librarydocumentation.

[Kenneth McDonald]

I have a module I'd like to document using the same style...

Thanks,
Ken

 

[beza1e1]

Do you think of pydoc? Just make comments in your code this way:

def add10(x):
"""this function adds ten to the given variable"""

Then save this into add.py and now (in the same directory):

pydoc add

Voila, your documentation.

 

[Kenneth McDonald]

Unfortunately, none of the documentation tools that use documentation
strings are suitable for full, serious documentation. There are a
number of reasons for this, and I'll touch on a few.

The obvious one is that there is no standard format for docstrings,
and this creates problems when trying to achieve a uniform look
across python documentation.

More seriously, there is a major problem with docstrings in that they
can only document something that has a docstring; classes, functions,
methods, and modules. But what if I have constants that are
important? The only place to document them is in the module
docstring, and everything else--examples, concepts, and so on--must
be thrown in there as well. But there are no agreed on formats and
processing pipelines that then allow such a large module docstring,
plus other docstrings, to produce a good final document.

I do tech writing for a living, so I have some idea of what I'm
talking about, I think

It's too bad that there is no equivalent of d'oxygen for Python. That
is a _nice_ program.


Thanks for the advice,
Ken

 

[Fredrik Lundh]

More seriously, there is a major problem with docstrings in that they
can only document something that has a docstring; classes, functions,
methods, and modules. But what if I have constants that are
important? The only place to document them is in the module
docstring, and everything else--examples, concepts, and so on--must
be thrown in there as well. But there are no agreed on formats and
processing pipelines that then allow such a large module docstring,
plus other docstrings, to produce a good final document.

fwiw, that's one of reason why I developed PythonDoc (which supports
JavaDoc-style documentation for all the usual suspects, but also for con-
stants, attributes, and variables)

It's too bad that there is no equivalent of d'oxygen for Python. That
is a _nice_ program.

doesn't doxygen support Python?

</F>

 

[Robert Kern]

fwiw, that's one of reason why I developed PythonDoc (which supports
JavaDoc-style documentation for all the usual suspects, but also for con-
stants, attributes, and variables)

The one thing I dislike about PythonDoc is that it puts everything into
comments and thus docstrings are usually neglected. I spend my entire
work day at an ipython shell, which makes querying docstrings very easy.

In [1]: set?
Type: type
Base Class: <type 'type'>
String Form: <type 'set'>
Namespace: Python builtin
Docstring:
set(iterable) --> set object

Build an unordered collection.

It disappoints me when I have to go open the ElementTree documentation
instead of querying the methods themselves.

--
Robert Kern
(e-mail address removed)

"In the fields of hell where the grass grows high
Are the graves of dreams allowed to die."
-- Richard Harter

 

[Brett Hoerner]

You get to spend all day in ipython?

Can I have your job?

 

[Michael Ekstrand]

It's too bad that there is no equivalent of d'oxygen for Python. That
is a _nice_ program.

I've been using epydoc (http://epydoc.sourceforge.net) for a while now,
and it's really nice. The output is very much in the style of Javadoc.
Its markup language lets you document module, class, and instance
variables and constants by mentioning them in the module or class's
docstring. It has its own markup languge (very JavaDoc-ish), but it
also supports JavaDoc and reStructuredText syntax.

- Michael

 

[Fredrik Lundh]

The one thing I dislike about PythonDoc is that it puts everything into
comments and thus docstrings are usually neglected.
teaser:

Help on module ElementTree:

NAME
ElementTree

DESCRIPTION
# ElementTree
# $Id: ElementTree.py 2324 2005-03-16 15:49:27Z fredrik $
#
# light-weight XML support for Python 1.5.2 and later.
...

CLASSES
Element
ElementTree
QName
TreeBuilder
XMLParser
iterparse

class Element
| Methods defined here:
|
| __delitem__(self, index)
|
| __delslice__(self, start, stop)
|
| __getitem__(self, index)
|
| __getslice__(self, start, stop)
...
Help on module ElementTree:

NAME
ElementTree

DESCRIPTION
The Element type is a flexible container object, designed to
store hierarchical data structures in memory.

CLASSES
Element
ElementTree
QName
TreeBuilder
XMLParser
iterparse

class Element
| Element class.
|
| Methods defined here:
|
| __delitem__(self, index)
| Deletes the given subelement.
|
| __delslice__(self, start, stop)
| Deletes a number of subelements.
|
| __getitem__(self, index)
| Returns the given subelement.
|
| __getslice__(self, start, stop)
| Returns a list containing subelements in the given range.
...

now, if I could only motivate myself to write a PEP on adding a __help__
hook to pydoc, so that the "help" command can be taught to do this all by
itself...

</F>

 

[Robert Kern]

You get to spend all day in ipython?

Can I have your job?

Well, I use the terms "work" and "day" rather loosely. I'm a graduate
student in geophysics. Somehow it rarely happens during daylight hours
and quite possibly wouldn't be called working by an outside observer.

--
Robert Kern
(e-mail address removed)

"In the fields of hell where the grass grows high
Are the graves of dreams allowed to die."
-- Richard Harter

 

[Reinhold Birkenfeld]

I have a module I'd like to document using the same style...

The Python Library documentation is written in LaTeX and converted to
HTML with latex2html. The relevant style and source files are in the
Python CVS tree.

Reinhold