[Numpy-discussion] Docstring page, out of date?
Tue Jan 22 00:27:19 CST 2008
Charles R Harris wrote:
> On Jan 21, 2008 6:09 PM, Jarrod Millman <firstname.lastname@example.org
> <mailto:email@example.com>> wrote:
> On Jan 21, 2008 2:03 PM, Matthew Brett <firstname.lastname@example.org
> <mailto:email@example.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.
epydoc from SVN works just fine once the following line is added at the top.
__docformat__ = "restructuredtext en"
"I have come to believe that the whole world is an enigma, a harmless enigma
that is made terrible by our own mad attempt to interpret it as though it had
an underlying truth."
-- Umberto Eco
More information about the Numpy-discussion