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

[David Cournapeau]

On Jan 22, 2008 3:18 PM, Jarrod Millman <millman at berkeley.edu> wrote:
> On Jan 21, 2008 7:56 PM, Charles R Harris <charlesr.harris at gmail.com> wrote:
> > On Jan 21, 2008 8:38 PM, Charles R Harris <charlesr.harris at gmail.com> wrote:
> > > 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.
>
> Hey Chuck,
>
> I am sorry that there has been so much confusion over the docstring
> standards.  As you know, the problems you are pointing out arose from
> the changes Travis made in December.  I added a warning to the top of
> the coding style guideline explaining the situation:
> http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines
> Once Travis writes a tool to render the docstrings, we can go ahead
> and update the instructions.
>

Thanks for the update in svn. It makes the current situation much
clearer, I think.

cheers,

David