[SciPy-user] Docstring standards for NumPy and SciPy

Travis Oliphant oliphant at ee.byu.edu
Wed Jan 17 17:55:58 CST 2007


Robert Kern wrote:

>Gary Ruben wrote:
>  
>
>>I think the :Returns: section is missing.
>>
>>Is see-also to be included at the end of the Notes section. For 
>>see-also, Ed says we can just add ":see: `frobble`" markup, so we should 
>>be able to just add a line like in the numpy example list on the wiki.
>>    
>>
>
>Personally, I'd like to encourage a prose explanation with each see-also
>reference. Doing so discourages the (relatively unhelpful, IMO) scattershot
>lists that we've been using so far.
>  
>

Any suggestions on how that might be done?

>  
>
>>I'm not clear on what the :Keywords: section adds. I think the 2nd 
>>example is just as good.
>>    
>>
>
>In plain text, it looks fine, but the code that interprets the two sections as
>(slightly) separate and outputs HTML and PDF as such remains to be written.
>  
>
I understood that epydoc translates :Parameters: and :Keywords: sections 
for us (see the consolidated fields section of 
http://epydoc.sourceforge.net/fields.html#fields )

Personally I'd like to use :Parameters: and then add an :Extra 
Parameters: section or something like that if just using a blank-line in 
the :Parameters: section is not useful enough.

>  
>
>>Reiterating my previous post about math, I'm arguing against LaTeX and 
>>matplotlib examples in these docstrings. LaTeX math and graphical 
>>examples would only be in the module-level docstrings, which won't be 
>>seen in such environments as ipython. This means they'll only ever 
>>appear to users as fully processed html pages or in pdfs. I think we can 
>>use the :math:'eqn' and .. math: idioms.
>>    
>>
>
>I don't know. Expressing math formulae is most important in function/class
>docstrings rather than modules. See most of the docstrings for the scipy.stats
>distributions, for example. And module docstrings will be seen in ipython and
>similar environments, too; I'm not sure why you think they won't. While I'm not
>a fan of reading raw LaTeX math expressions in plain text, it beats the
>readily-available alternatives.
>  
>

I agree that we can't really just ignore the problem.     I could live 
with :math:`eqn`  or :latex-math:`eqn` (although I would really prefer 
the abbreviations :m:`eqn` and :lm:`eqn`).   Abbreviations are just fine 
in my mind for something that is used often enough.

Ideally, we could use $$eqn$$  (I saw the double dollar signs used in 
ASCIIDOC).

-Travis


-Travis





More information about the SciPy-user mailing list