[SciPy-user] Docstring standards for NumPy and SciPy

[Robert Kern]

Travis Oliphant wrote:
> Robert Kern wrote:
> 
>> 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.
> 
> Any suggestions on how that might be done?

Not writing any code to try to parse the "see-alsos" into simple lists. That's
as elegant a solution as you get, IMO.  :-)

More seriously, simply making the "See also" section unstructured, and writing
the initial examples with appropriate verbosity will probably suffice.

>>> 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.
>>  
> I understood that epydoc translates :Parameters: and :Keywords: sections 
> for us (see the consolidated fields section of 
> http://epydoc.sourceforge.net/fields.html#fields )

Yes, I was referring to the hypothetical code that would parse the blank line in
the single :Parameters: section as a separator between parameters and keywords.

Personally, I simply prefer having explicit, separate sections here, and don't
care what the :Names: are.

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