What tools are used to write and generate Python Librarydocumentation.

[Robert Kern]

Fredrik Lundh wrote:
> Kenneth McDonald wrote:
> 
>>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)

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 at ucsd.edu

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