I have a module I'd like to document using the same style...
Thanks,
Ken
Thanks,
Ken
-
-
Re: What tools are used to write and generate Python Library documentation.
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.
-
Re: What tools are used to write and generate Python Librarydocument ation.
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
On Sep 27, 2005, at 1:21 AM, beza1e1 wrote:
[color=blue]
> 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.
>
> --
> http://mail.python.org/mailman/listinfo/python-list
>[/color]
Comment
-
Re: What tools are used to write and generate PythonLibrarydo cumentation.
Kenneth McDonald wrote:
[color=blue]
> 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.[/color]
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)
[color=blue]
> It's too bad that there is no equivalent of d'oxygen for Python. That
> is a _nice_ program.[/color]
doesn't doxygen support Python?
</F>
Comment
-
Re: What tools are used to write and generate PythonLibrarydo cumentation.
Fredrik Lundh wrote:[color=blue]
> Kenneth McDonald wrote:
>[color=green]
>>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.[/color]
>
> 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)[/color]
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
rkern@ucsd.edu
"In the fields of hell where the grass grows high
Are the graves of dreams allowed to die."
-- Richard Harter
Comment
-
Re: What tools are used to write and generate Python Librarydocument ation.
You get to spend all day in ipython?
Can I have your job?
Comment
-
Re: What tools are used to write and generate Python Librarydocument ation.
On Sep 27, 2005, at 12:45 PM, Kenneth McDonald wrote:[color=blue]
> It's too bad that there is no equivalent of d'oxygen for Python. That
> is a _nice_ program.[/color]
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 reStructuredTex t syntax.
- Michael
Comment
-
Re: What tools are used to write and generatePythonL ibrarydocumenta tion.
Robert Kern wrote:
[color=blue]
> The one thing I dislike about PythonDoc is that it puts everything into
> comments and thus docstrings are usually neglected.[/color]
teaser:
[color=blue][color=green][color=darkred]
>>> from elementtree import ElementTree
>>> help(ElementTre e)[/color][/color][/color]
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__(sel f, index)
|
| __delslice__(se lf, start, stop)
|
| __getitem__(sel f, index)
|
| __getslice__(se lf, start, stop)
...
[color=blue][color=green][color=darkred]
>>> import pythondoc
>>> help(ElementTre e)[/color][/color][/color]
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__(sel f, index)
| Deletes the given subelement.
|
| __delslice__(se lf, start, stop)
| Deletes a number of subelements.
|
| __getitem__(sel f, index)
| Returns the given subelement.
|
| __getslice__(se lf, 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>
Comment
-
Re: What tools are used to write and generate PythonLibrarydo cumentation.
Brett Hoerner wrote:[color=blue]
> You get to spend all day in ipython?
>
> Can I have your job?[/color]
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
rkern@ucsd.edu
"In the fields of hell where the grass grows high
Are the graves of dreams allowed to die."
-- Richard Harter
Comment
-
Re: What tools are used to write and generate Python Library documentation.
Kenneth McDonald wrote:[color=blue]
> I have a module I'd like to document using the same style...[/color]
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
Comment
Comment