[SciPy-user] Docstring standards for NumPy and SciPy
millman at berkeley.edu
Fri Jan 12 09:33:49 CST 2007
It seems to me that the discussion about the proposed documentation
standard is well enough along that it is time for some decisions to be
To help facilitate this, I created a wiki page to try and capture the
To help simplify the discussion, I split the issue into 2 parts:
1. content (or the sections of the docstring)
I think that the basic content or sections are more or less agreed
upon and I believe the sections I listed were what everyone was
agreeing on. Hopefully, I haven't misunderstood. There are some minor
unresolved points like whether to use Inputs or Parameters. But that
should be easy to resolve once we decide which markup to use.
>From what I can see it looks like there are 2 main markup choices:
m2. preST (pseudo-reST)
My understanding is that most people have a slight preference for
using reST. Travis is a strong support of preST because of the
increased line-noise in reST. The main argument for reST seems to be
that it is a pre-existing standard.
If there are no more major arguments to be made for either markup
choice, I think we should vote or come to some sort of agreement on
whether to use reST or preST by early next week.
Once the markup is chosen, I will update the wiki.
Computational Infrastructure for Research Labs
10 Giannini Hall, UC Berkeley
More information about the SciPy-user