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

[Robert Kern]

Charles R Harris wrote:
> 
> 
> On Jan 21, 2008 6:09 PM, Jarrod Millman <millman@berkeley.edu 
> <mailto:millman@berkeley.edu>> wrote:
> 
>     On Jan 21, 2008 2:03 PM, Matthew Brett <matthew.brett@gmail.com
>     <mailto: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
>     <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"

-- 
Robert Kern

"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