[SciPy-dev] [SciPy-user] Docstring standards for NumPy and SciPy

[Robert Kern]

Travis Oliphant wrote:
> After some more lively discussion, here is my latest proposal.  We will 
> use reST for the docstrings with specific sections expected as given.  
> The Notes and Examples section are optional but the Examples section is 
> strongly encouraged.

There's another section that we should encourage (since authors tend not to
document it otherwise):


Raises
------
ValueError if the input matrix is not square.
LinAlgError if the input matrix is not symmetric positive definite.


I don't think it needs any special parsing; it can be unstructured.

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