[SciPy-dev] consistency for documenting mathematical functions in numpy.core.umath

[David Goldsmith]

On Wed, Oct 21, 2009 at 8:33 PM, Robert Kern <robert.kern at gmail.com> wrote:

> On Wed, Oct 21, 2009 at 22:05, Angel Yanguas-Gil
> <angel.yanguas at gmail.com> wrote:
> > Hi!
> >
> > I have noticed that the structure of the docstrings (sections, etc.)
> > of the mathematical functions defined in numpy.core.umath change from
> > function to function. Maybe it is an old topic but, would it be worth
> > to unify them - i.e., using the same reference sources, same section
> > structure, consistent cross-reference between methods etc. ?
>
> The standard is here:
>
>  http://projects.scipy.org/numpy/browser/trunk/doc/HOWTO_DOCUMENT.txt
>
> You can help fix nonconforming docstrings here:
>
>  http://docs.scipy.org/numpy/Front%20Page/
>
> You may be looking at older versions. There has been substantial
> effort put into improving this aspect of the docstrings recently.
>
> --
> Robert Kern
>

In particular, the docstrings you generally refer to *should* all have been
modified to conform to the standard Robert refers to above (note, however,
that many of the sections are optional: if a section is irrelevant for a
particular object, e.g., Returns often is, or is empty, e.g., References
often is, then we just omit it altogether).  However, generally, we make
such mods using our special wiki app (Robert's second link above), not in
the code itself; changes made in the wiki are not *automatically* merged
into the code; and we have a large backlog of docstring changes (as well as
code changes) for which merge is pending.  If you can be more specific as to
which docstrings do not conform to the above standard, we (or you) can check
to see if they are at least compliant in the wiki, in which case they will
be merged, hopefully this weekend, and if they aren't, well then, we have
some substantive work to do.

DG
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20091021/8cd9d8b8/attachment.html>