[SciPy-user] Docstring standards for NumPy and SciPy
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.
More information about the SciPy-user