[SciPy-user] Docstring standards for NumPy and SciPy

Travis Oliphant oliphant at ee.byu.edu
Wed Jan 10 11:39:46 CST 2007


Fernando Perez wrote:

>I should add though, that I agree with Alan in preferring plain reST
>against pseudo-reST.  My brain is starting to fill up with all the
>'enhanced plaintext' formats floating around: Trac, Moin, reST,
>epytext, ... ( I'm not even sure if Trac and Moin are 100% identical
>anymore).  For that reason, I'd much rather just learn one of them and
>use it well.  Keeping track of multiple slightly different formats
>becomes a major PITB (pain in the brain).  It's actually much harder
>than keeping /very/ different formats sorted out, since our brain
>seems pretty good at creating 'cognitive buckets' for widely disparate
>things, but those that are oh-ever-so-slightly different easily blur
>into one another.
>  
>
Probably not.  I know that Moin and reST are not identical.

Problem is that Moin does a better job with tables than reST does.

>So while I'm +100 for Travis' proposal in general, I'd vote for it
>just following plain reST (with the LaTeX support that has been
>discussed here) without adding yet a new 'numpytext' format.
>  
>
But, that's just it we have to "add latex" support which is already 
going to be non-standard.  The way reST defines directives is not pretty.

Putting

.. :latex-math:

everywhere is line-noise to me.  

If the only issue is having automated tools.  We can easily translate to 
those tools from our format.

-Travis




More information about the SciPy-user mailing list