[SciPy-user] Docstring standards for NumPy and SciPy

Robert Kern robert.kern at gmail.com
Wed Jan 17 16:58:33 CST 2007


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.

> 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.

> 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.

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
 that is made terrible by our own mad attempt to interpret it as though it had
 an underlying truth."
  -- Umberto Eco


More information about the SciPy-user mailing list