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

Travis Oliphant oliphant at ee.byu.edu
Wed Jan 17 11:57:14 CST 2007


Alan G Isaac wrote:

>On Tue, 16 Jan 2007, Travis Oliphant apparently wrote: 
>  
>
>>In summary, my biggest issues with just straight 
>>restructured Text are 
>>1) back-ticks in parameter lists. 
>>    
>>
>
>I understood Ed to say:
>
>1) this can probably be dispensed with easily enough
>2) if dispensed with, we may lose cross refs from the
>   parameters?
>
>I assume I misunderstood (2), since this is just a matter of 
>how definition lists are parsed in consolidated fields, and 
>definition lists definitely do not require the back tics.  
>So I *think* Ed is saying both that this problem can be 
>overcome and that he is willing to help with it.
>  
>
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?

This would be fine.

I'd like an additional "field" name to describe little used parameters 
so that functions with a large number of keyword argument can still be 
well documented without cluttering the main parameters list.  Is that 
possible?

Where are these standard field names used?

>
>  
>
>>2) the way math is included
>>    
>>
>
>I understood Ed to say that for inline math we could just 
>make LaTeX the default role, so that we write e.g., 
>`f(x)=x^2`.  Back ticks look at least as good as dollar 
>signs, IMO.
>  
>

I don't have a problem with back-ticks used for math. 

>The cost is that cross refs then must be explicitly marked.
>How important are these considered to be for the 
>documentation?  (How did you intend to mark them?)
>
>I did not get a sense of how easy it would be to make dollar  
>signs special (so they could be used to indicate a math role).
>I guess it would not be hard, but I feel 
>pretty confident that this would NOT be welcomed as some 
>kind of patch to reST.  (But I'm just a user.)
>
>
>  
>
>>3) doesn't understand Moin Moin tables 
>>    
>>
>
>This seems just a matter of hacking reST, it seems to me.  
>I hazard that the reST developers would welcome a patch to 
>handle Moin Moin tables.  In the meantime I ask, what 
>features missing from reST tables would actually be used?
>
>
>  
>
I don't care so much about this.  I'm not wedded to Moin Moin's 
definition of tables except it seemed pretty minimialistic and easy to use.

>
>  
>
>>I also don't really like the way bold, italics, and 
>>courier are handled.  My favorite is now *bold* /italics/ 
>>and  `fixed-width`. 
>>    
>>
>
>This seems to me not worth haggling over.  Right?
>  
>
I agree. I'm not that concerned about it. 

I think if we can agree on a suitable description of the parameters list 
and on what to do about including math (I don't think there will be a 
lot of math in docstrings but there may need to be some, so we ought to 
think about it) then we are there for using reST in docstrings.

I guess my major reaction to reST was the prevalent use of backticks in 
parameter descriptions.  I can see now that this is not a requirement of 
reST but only a convention.  I'd prefer a different convention for 
NumPy/SciPy.


-Travis




More information about the SciPy-user mailing list