[Numpy-discussion] Docstring page, out of date?

Charles R Harris charlesr.harris@gmail....
Mon Jan 21 21:38:38 CST 2008


On Jan 21, 2008 6:09 PM, Jarrod Millman <millman@berkeley.edu> wrote:

> On Jan 21, 2008 2:03 PM, Matthew Brett <matthew.brett@gmail.com> wrote:
> > Search for the docstring standard, I hit this:
> >
> > http://www.scipy.org/DocstringStandard
>
> Good catch, I didn't know this page existed.  If I recall correctly,
> Keir Mierle showed up on the mailing list around the time we were
> discussing the docstring standard.  He proposed to do some work, but
> then must have gotten busy with something else.  In particular, I
> believe he was interested in seeing a unified docstring standard for
> numpy, scipy, and matplotlib.  I guess he put this page up during that
> period.  I went ahead and deleted it, since it conflicts with the
> official docstring standard.
>
> > but I think the current thinking is this:
> >
> > http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines
> >
> > Is that correct? Does the first page apply to matplotlib in some way?
> > Should we change the first page to match the second now?
>
> Yes.  That page is autogenerated from the official coding standard
> that is in the numpy trunk.  One of the nice features of trac is that
> it can render restructured text from the svn repository.  This helps
> us keep from having duplicate information that needs to be kept in
> sync by hand.
>

If I hit the source code link in the generated  html, it looks like that
page was generated from the old document format. The new document format
doesn't produce output that looks anything like that and epydoc generates a
couple of warnings:

| File /home/charris/workspace/numpy/numpy/doc/example.py, line 19, in
| example.foo
|   Warning: Line 24: Wrong underline character for heading.
|   Warning: Lines 27, 30, 32, 37, 39, 41, 43, 48, 50: Improper paragraph
|            indentation.

The new document format requires a preprocessor that has yet to be written.

Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://projects.scipy.org/pipermail/numpy-discussion/attachments/20080121/0c7cf670/attachment-0001.html 


More information about the Numpy-discussion mailing list