Agreed that a reST based standard would be very useful.

One point that is important to me (and many scientific users) is how the docstring looks in a terminal. Numpy has been developing a standard for docstrings and writing docs that both looks good in plain text and in docs rendered with Sphinx. http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines This is quickly becoming a standard for scientific projects (numpy, scipy, matplotlib, ipython etc). For an example see http://docs.scipy.org/numpy/docs/numpy.core.multiarray.arange/, click "source" for plain text version. Basic format is:

"""Summary line.

Parameters
------------
param1 : int
    Description of param1. Can be multi-line.
param2: array
   Description of param2.

Returns
-------
val1 : float

Example
-------
<examples in doctest format>
"""

There is also a very nice wiki doc editor with svn merging support (into the wiki automatic, patch generation for import into svn) here: http://docs.scipy.org/numpy/docs/.

As far as I can tell the epydoc standard is not nearly as readable as the numpy standard in plain text, so please consider the latter or something similar for adoption.

Best regards,
Ralf