[SciPy-user] Docstring standards for NumPy and SciPy
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.
everywhere is line-noise to me.
If the only issue is having automated tools. We can easily translate to
those tools from our format.
More information about the SciPy-user