[SciPy-user] Docstring standards for NumPy and SciPy
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.
named : type
output : type
variables : type
Is this possible. If there is just one output then
:return var: Explanation
:rtype var: type
More information about the SciPy-user