[SciPy-user] Docstring standards for NumPy and SciPy

Jarrod Millman 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
reached.

To help facilitate this, I created a wiki page to try and capture the
main proposals:
http://projects.scipy.org/scipy/numpy/wiki/DocstringStandards

To help simplify the discussion, I split the issue into 2 parts:
  1. content (or the sections of the docstring)
 2. markup

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:
  m1. reST
  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.

Thanks,

-- 
Jarrod Millman
Computational Infrastructure for Research Labs
10 Giannini Hall, UC Berkeley
phone: 510.643.4014
http://cirl.berkeley.edu/


More information about the SciPy-user mailing list