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

[Fernando Perez]

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

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

+100

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

OK


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)
Docstring:
    Return the natural logarithm of x.

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

    Parameters
    ----------
    x : array_like

    Returns
    -------
    array_like

    Examples
    --------
    >>> import math

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

    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)
    True


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
File:
/home/fperez/usr/opt/lib/python2.5/site-packages/numpy/core/fromnumeric.py
Definition:     np.cumsum(a, axis=None, dtype=None, out=None)
Docstring:
    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....

Cheers,


f