# [SciPy-user] [SciPy-dev] Docstring standards for NumPy and SciPy

Robert Kern robert.kern at gmail.com
Wed Jan 17 18:12:22 CST 2007

Edward Loper wrote:
> [Travis]
>> Great.   Getting rid of back-ticks in the parameters section would
>> help
>> a great deal.
>>
>> So does this mean
>>
>> :Parameters:
>>    a : array
>>         this is something
>>    b : int
>>         this is a scalar input
>>
>> could be how argument parameters are specified?
>
> Indeed.  I just made & commited the change (epydoc subersion revision
> 1418).

Excellent. May I add some, possibly troublesome examples to the menagerie that I
would like to be able to parse? I'll check out SVN epydoc tonight to play with
it myself.

:Parameters:
x : array
y : array
The x and y coordinates.

:Parameters:
f : callable
The function to optimize.
*args
Positional arguments to apply to f().
**kwds
Keyword arguments to apply to f().

:Parameters:
f : callable
The function to optimize.
*args, **kwds
Additional arguments to apply to f().

# I'd settle for this:
:Parameters:
f : callable
The function to optimize.
*args
**kwds
Additional arguments to apply to f().

>> I don't have a problem with back-ticks used for math.
>
> Keep in mind, though, that using bare back-ticks for math means they
> can't also be used for cross-references.  I suspect that cross-
> references will be more common..  not just in see-also type fields,
> but also as hyperlinks in sentences such as "precision is determined
> by the flooble instance variable."  If you use bare back-ticks for
> math, then that would need to become "precision is determined by
> the :xref:flooble instance variable.  You suggest later that you
> don't expect there to be a lot of math embedded in docstrings, in
> which case the slightly more verbose math:\sum_i^Ni^2 doesn't seem
> like as much of a big deal.

I agree that cross-references will probably be more common. Especially n.

--
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
`