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

[Charles R Harris]

On Jan 21, 2008 8:38 PM, Charles R Harris <charlesr.harris at gmail.com> wrote:

>
>
> On Jan 21, 2008 6:09 PM, Jarrod Millman <millman at berkeley.edu> wrote:
>
> > On Jan 21, 2008 2:03 PM, Matthew Brett <matthew.brett at 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.
>

Since epydoc also works for compiled modules, I think the easiest way to do
that is to fork epydoc. The syntax of the new markup is context sensitive -
single types are no longer in {} - so parsing will be a bit more
complicated. As ReST is not part of the current document markup, we might
consider removing the parts of the document documentation that refer to it.

Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20080121/f9876b0f/attachment.html>