[SciPy-user] Docstring standards for NumPy and SciPy

[Bill Baxter]

On 1/18/07, Gary Ruben <gruben at bigpond.net.au> 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.

That sounds like it will be worse than the backticks in the parameters section.
For example, from the Numpy Example List, mean() has this:

See also: average, median, var, std, sum

So you're saying in the docstrings that will become

  :see: `average`, `median`, `var`, `std`, `sum`

Or worse:
  :see:`average`, :see:`median`, :see:`var`, :see:`std`, :see:`sum`

I think a good See Also list is one of the most useful things a
package like SciPy can have in its documentation.   I can't count the
number of times I've learned about useful and relevant functions in
Matlab thanks to its copious See Also's.

--bb