[SciPy-user] Docstring standards for NumPy and SciPy

[Alan Isaac]

I am not trying to "argue" for reST+epydoc, but rather to
add my perspective on some of the arguments pro and con.
Here are some issues that have been raised.
I will copy Ed Loper, in case he wants to comment.

Alan Isaac

Must items (e.g., parameters) in a consolidated field be 
marked as interpreted text (with back ticks).
    Yes.  It does seem redundant, so I will ask why.
Would it not be nice to have :Inputs: and :Outputs: 
consolidated fields as synonyms for :Parameters:
and :Returns:?
    Yes!  Perhaps Ed Loper would be willing to add this.
Can new fields be added?
    http://epydoc.sourceforge.net/fields.html#newfield
    (In addition, the author has added fields in response
    to requests.)
Is Epydoc easily customizable?
    In what ways?  It is easy to add new fields
    (see above), but I do not know about new
    consolidated fields.
Can you put type and precision right after the variable
in a :Parameters: list?
    http://epydoc.sourceforge.net/fields.html#rst
    (Yes; see the very last example)
Is table support adequate in reST?
    http://docutils.sourceforge.net/docs/ref/rst/directives.html#tables
    So *maybe* not, although I am not currently imagining
    a table that will be used in documentation that cannot
    be accommodated (are elements in multiple cells really 
    needed?).  And of course, any plain text table can be
    retained as a literal block.
Is the use of directives "cluttered"?
    Not in my opinion.  For example::

        \[
        f(x) = x^2
        \]

    does not seem more cluttered to me than::

        .. latex-math::
                
                f(x) = x^2
    However it would be nice to keep the default role for
    math, so we could inline `f(x)=x^2` rather than
    :latex-math:`f(x)=x^2`.  It may be worth asking whether
    epydoc developers would be willing to pass $f(x)=x^2$
    as latex-math.
Are there date and version fields?
    There are, called 'since' and 'version'.
Why use underlining to define sections?
    So that they are really sections.
    The indented examples will display fine
    but will not give access to sectioning controls.