[SciPy-user] Docstring standards for NumPy and SciPy

Fernando Perez fperez.net at gmail.com
Wed Jan 10 10:05:14 CST 2007


On 1/10/07, Alan G Isaac <aisaac at american.edu> wrote:
> On Wed, 10 Jan 2007, Travis Oliphant apparently wrote:
> > I'm strongly against line-noise in the docstrings.
>
> Although I am a user not a developer, I have some experience
> with reStructuredText and epydoc, and I wonder if they are
> as "noisy" as you fear.  In general I think it gives
> a very clean and readable look, and links are particularly
> clean.  A big advantage is that the tools for processing
> exist and are very good.  The idea that reST introduces
> a lot of "noise" is contrary to my limited experience.  Do
> I recall that Fernando Perez was exploring using the
> latex-math support in documentation: if so, maybe he can
> report on the experience.  (I have used it in documents,
> where it works great, but not in documentation.)

No, it wasn't me.  I'm /interested/ in it, but I haven't used it yet.

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.

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.

Cheers,

f


More information about the SciPy-user mailing list