[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