[Design] help? review documentation autogenerators

[Michael McLay]

On Friday 28 February 2003 03:02 pm, Kaitlin Duck Sherwood wrote:
> Has anybody used software that creates documentation from source code,
> e.g. JavaDoc and Doxygen?
>
> We recognize the importance of good developer documentation and were
> wondering if (hoping) that some such tool would help.
>
> If you know about any of these doc tools, could you please add what you
> know to this wiki page?
> 	http://wiki.osafoundation.org/bin/view/Main/CodeToDocumentationSoftware
>
> Obviously, OSAF is most interested in tools for Python, presumably that
> take advantage of the docstring.
>
> I'm also a little curious to hear opinions about which features are
> good/bad/ugly even in programs that only work for other languages.

Robin.K.Friedrich wrote the original gendoc for Python many years ago. 
Serveral other packages have been created since and reside in various 
repositories. (The docutils [1] project on sourceforge is a good starting 
point.) The core distribution includes the pydoc [2] module. It is used by 
the help() command that is avaialble at the interactive python session 
prompt. The package also can be used to generate HTML. 

There is also a python PEP on structured text [3]. This is the formal 
specification for writing structured text that is used to generate Python PEP 
specifications. I'm not sure if this is the same formal structured text 
notation used in Zope. I also recall some discussion of using structured text 
in doc strings, but I don't know if there was an outcome to that discussion. 
The Python mailing list would probably answer the question. 

The list of references at the end of [2] might also be of interest. They point 
to the docutils project on soruceforge as well as other resources.

[1] http://docutils.sourceforge.net/
[2] http://web.pydoc.org/2.2/pydoc.html (See interactive help() session 
below.)
[3] http://www.python.org/peps/pep-0012.html

[mclay@l5sg dcim]$ python
Python 2.2.1 (#1, Sep  9 2002, 09:26:21)
[GCC 3.2 (Mandrake Linux 9.0 3.2-1mdk)] on linux-i386
Type "help", "copyright", "credits" or "license" for more information.
>>> import pydoc
>>> help(pydoc)
Help on module pydoc:

NAME
    pydoc - Generate Python documentation in HTML or text for interactive use.

FILE
    /usr/lib/python2.2/pydoc.py

DESCRIPTION
    In the Python interpreter, do "from pydoc import help" to provide online
    help.  Calling help(thing) on a Python object documents the object.

    Or, at the shell command line outside of Python:

    Run "pydoc <name>" to show documentation on something.  <name> may be
    the name of a function, module, package, or a dotted reference to a
    class or function within a module or module in a package.  If the
    argument contains a path segment delimiter (e.g. slash on Unix,
    backslash on Windows) it is treated as the path to a Python source file.

    Run "pydoc -k <keyword>" to search for a keyword in the synopsis lines
    of all available modules.

    Run "pydoc -p <port>" to start an HTTP server on a given port on the
    local machine to generate documentation web pages.

    For platforms without a command line, "pydoc -g" starts the HTTP server
lines 1-27