[SciPy-user] Docstring standards for NumPy and SciPy

[Gary Ruben]

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.

I'm not clear on what the :Keywords: section adds. I think the 2nd 
example is just as good.

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.

Gary R.

Travis Oliphant wrote:
> After some more lively discussion, here is my latest proposal.  We will 
> use reST for the docstrings with specific sections expected as given.  
> The Notes and Examples section are optional but the Examples section is 
> strongly encouraged.
> 
> """
> one-line summary not using variable names or the function name
> 
> A few more sentences giving an extended description
> 
> :Parameters:
>     var1 : any-type information
>         Explanation
>     var2 : type
>         Explanation
>     long_variable_name
>         Explanation
> 
> :Keywords:
>     only_seldom_used_keywords : type
>         Explanation
>     any_common_keywords
>         Should be placed in the parameters section
> 
> Notes
> ------
> 
> Any algorithm or other notes that may be needed.
> 
> 
> Examples
> --------
> 
> Doctest-formated examples
> """
> 
> 
> Remaining questions:
> 
> 1) I'm still unclear on how to include math --- please help.
> 2) I'm still unclear on what to do about see-also.  I know we want to be 
> conservative in how this is used, but perhaps ought to give some help.
> 3) I don't really like using :Keywords: like I'm using it above.  I 
> would prefer another special field name   that epydoc understands.  
> Perhaps we can just use spacing in the :Parameters: section to convey 
> the same split in the authors interpretation of the parameters.
> 
> Something like this:
> 
> :Parameters:
>     var1 : any-type information
>         Explanation
>     var2 : type
>         Explanation
>     long_variable_name
>         Explanation
> 
>     only_seldom_used_keywords : type
>         Explanation
>     any_common_keywords
>         Should be placed in the parameters section
> 
> 
> -Travis