[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().
# I don't care too much about this one, but it'd be nice.
: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
that is made terrible by our own mad attempt to interpret it as though it had
an underlying truth."
-- Umberto Eco
More information about the SciPy-user
mailing list