[SciPy-user] Docstring standards for NumPy and SciPy

David Huard david.huard at gmail.com
Wed Jan 10 11:07:51 CST 2007


Hi,
I think we should stick with ReST, but define our own roles and directives
(Input, Output, etc). This would lead to a standard  close to what Travis
proposes, with some small differences:
fields would be defined as :Field: instead of Field:,
mathematical formulas, ie :math: instead of $, although we could  probably
do something about that too.

I started to implement the standard discussed before the holidays by hacking
epydoc. I managed to add Input and Output fields, but it's not pretty.
Epydoc does not seem to be easily customizable, hence the suggestion to
define reST roles for the fields Travis proposed and make minimal changes to
epydoc to integrate those new fields.

In any case, it would be time to get a documention folder in the trunk or
sandbox to store:
 * patches to docutils and epydoc,
 * a typical docstring to use as a benchmark,
 * a documentation makefile,
 * documentation guidelines.

Cheers,

David






2007/1/10, Pierre GM <pgmdevlist at gmail.com>:
>
> On Wednesday 10 January 2007 10:55, Alan G Isaac 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.
>
> My 2c:
>
> I'd be happier if we'd stick to reST. As Alan mentioned, the format is
> simple,
> not cluttered, and the tools are already here. Why yet another format ?
> Travis, what do you consider as 'noise' in the rest fields ?
>
> I also second Stefan's suggestion: I'm not really interested in knowing
> who
> wrote a particular piece of code when trying to access the docstring of a
> function.
>
> Now, Travis, if your example is very generic and covers also the docstring
> of
> a full module, that's different. But then it might be worth to add
> some :date: and :version: fields.
>
>
> > """
> > one-line summary not using variable names or the function name
> >
> > A few sentences giving an extended description.
> >
> > :Parameters:
> >
> >    `var1`
> >         Explanation
> >    `variable2`
> >         Explanation
>
> I like precision the type of input and the default directly in front of
> the
> variables:
> :Parameters:
>         - `var1` : ndarray
>                 Explanation
>         - `var2` : Boolean *[False]*
>                 Explanation
> _______________________________________________
> SciPy-user mailing list
> SciPy-user at scipy.org
> http://projects.scipy.org/mailman/listinfo/scipy-user
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://projects.scipy.org/pipermail/scipy-user/attachments/20070110/95152b09/attachment-0001.html 


More information about the SciPy-user mailing list