[SciPy-user] Docstring standards for NumPy and SciPy

Travis Oliphant oliphant at ee.byu.edu
Wed Jan 17 23:09:57 CST 2007


Edward Loper wrote:
> One issue with both of these solutions is that they will *not* make  
> any distinction between the two sets of arguments in the generated  
> html/pdf output.  It sounds like you *do* want this distinction to  
> get preserved in the generated output.  If that's the case, then I  
> think we'll need to define a new field tag.
>   

I think you are right.   Probably something like :OtherParameters: or 
something like that.  I prefer white-space as in  :Other Parameters: if 
it can be made to work.

> I think the standard name should be something like :math:`foo`, but  
> that it should be easy enough to expose a hook so you can  
> register :m:`foo` as an alias for :math:`foo`.
>   

This is completely fine.   I think two aliases are useful

1) :lm:`foo` for :latex-math:`foo`  (can we use '-' in a standard name?)

2) :m:`foo` for :math:`foo`


One issue that hasn't been addressed is the  :return: field.   In 
NumPy/SciPy tuples are often returned and meant to be called so that 
multiple outputs are returned. 

It would be best to have an :Returns: consolidated field that looks 
very-much like the :Parameters: section.


:Returns:
  named : type
      Explanation
  output : type
      Explanation
  variables : type
      Explanation

Is this possible.  If there is just one output then

:return var: Explanation
:rtype var: type

would work.


-Travis






More information about the SciPy-user mailing list