[SciPy-user] Docstring standards for NumPy and SciPy

[Travis Oliphant]

Travis Oliphant wrote:

>There was a lively discussion on the SciPy List before Christmas 
>regarding establishing a standard for documentation strings for NumPy / 
>SciPy.
>  
>

After some more lively discussion, here is my latest proposal.  We will 
use reST for the docstrings with specific sections expected as given.  
The Notes and Examples section are optional but the Examples section is 
strongly encouraged.

"""
one-line summary not using variable names or the function name

A few more sentences giving an extended description

:Parameters:
    var1 : any-type information
        Explanation
    var2 : type
        Explanation
    long_variable_name
        Explanation

:Keywords:
    only_seldom_used_keywords : type
        Explanation
    any_common_keywords
        Should be placed in the parameters section

Notes
------

Any algorithm or other notes that may be needed.


Examples
--------

Doctest-formated examples
"""


Remaining questions:

1) I'm still unclear on how to include math --- please help.
2) I'm still unclear on what to do about see-also.  I know we want to be 
conservative in how this is used, but perhaps ought to give some help.
3) I don't really like using :Keywords: like I'm using it above.  I 
would prefer another special field name   that epydoc understands.  
Perhaps we can just use spacing in the :Parameters: section to convey 
the same split in the authors interpretation of the parameters.

Something like this:

:Parameters:
    var1 : any-type information
        Explanation
    var2 : type
        Explanation
    long_variable_name
        Explanation

    only_seldom_used_keywords : type
        Explanation
    any_common_keywords
        Should be placed in the parameters section


-Travis