[Numpy-discussion] [SciPy-dev] Doc-day

Fernando Perez fperez.net@gmail....
Sat Dec 29 19:59:27 CST 2007

On Dec 29, 2007 6:51 PM, Charles R Harris <charlesr.harris@gmail.com> wrote:

> If not, we should
> definitely decide on the structure of the docstrings and stick to it.


I'm about to commit docstrings for scimath (what I started yesterday).
 After some fixes to the numpy build, I can now work in-place and get
things like

tlon[~]> nosetests --with-doctest numpy.lib.scimath
Ran 7 tests in 0.660s


Which is nice.  For now I'm adhering to what was in the guide:

>>> log?
Type:           function
Base Class:     <type 'function'>
Namespace:      Interactive
File:           /home/installers/src/scipy/numpy/numpy/lib/scimath.py
Definition:     log(x)
    Return the natural logarithm of x.

    If x contains negative inputs, the answer is computed and returned in the
    complex domain.

    x : array_like


    >>> import math

    >>> log(math.exp(1))

    Negative arguments are correctly handled (recall that for negative
    arguments, the identity exp(log(z))==z does not hold anymore):

    >>> log(-math.exp(1)) == (1+1j*math.pi)

But it's easy enough to fix them if a change is made.  But let's
settle this *soon* please, so that if changes need to be made it's
just a few, and we can just move on.

At this point we just need *a* decision.  It doesn't need to be
perfect, but any docstring is better than our canonical:

>>> np.cumsum?
Type:           function
Base Class:     <type 'function'>
Namespace:      Interactive
Definition:     np.cumsum(a, axis=None, dtype=None, out=None)
    Sum the array over the given axis.

    Blah, Blah.

I got that 'Blah blah' while lecturing to 20 developers and scientists
at a workshop at NCAR (the National Center for Atmospheric Research in
Boulder), projected on a 20 foot-wide screen.  A bit embarrassing, I
must admit.

So please, no more code without full docstrings in numpy/scipy....



More information about the Numpy-discussion mailing list