[SciPy-dev] Namespaces in documentation (was: ANN: NumPy/SciPy Documentation Marathon 2008)

[Stéfan van der Walt]

Hi Pauli, all

I postponed this discussion for a while, so that we could write some
documentation and get a feeling for what works and what doesn't.  We
now have enough experience to make an informed decision.

When a person codes, and you find yourself repeating certain
constructs over and over, what do you do?  You create a function or a
short-cut.  We have a similar situation here.  In the documentation,
we're seeing

"import numpy as np"
"import matplotlib.pyplot as plt"

all too often.  We could easily replace the calls to "np" with calls
to "numpy", but it feels clumsy.

"import numpy as np"

is a community standard.  I'd like to repeat that this does *not* mean
that we want to force anyone to use it in their own code; but it *is*
a standard inside numpy, scipy and matplotlib.  As such, I think it is
fair that we encourage our users to make use of it.

I propose we adopt it for the documentation.  I know that the first
argument against it would be that users cannot "cut-and-paste" code
directly into a Python session.  On that front, I have good news.  A
patch has been accepted into IPython that allows *directly* pasting
docstrings, i.e., strings like ">>> x + 3", and executing them.  This
is achieved using the "cpaste" (or %cpaste) command.  Fernando Perez
has committed to providing "np", "sp" and "plt" in the pylab profile,
obtained by running "ipython -pylab".  This should put to rest any
concerns for new users not being able to execute the examples.

The other concern is that some (seasoned) users prefer different
contractions: N, npy, etc.   I'm afraid we cannot accommodate every
taste, and we cannot afford to compromise the documentation because we
cannot agree on a short form of `numpy`.

So, in short, I propose:

1) Using the standard contractions: np for numpy, sp for scipy, plt for pylab
2) When writing examples for functions in a sub-module, make no
further assumptions.  A docstring from fft would therefore use

import numpy.fft      # numpy.fft is not imported by default
z = np.fft.fft2(x)

in an example.

3) See Also sections may refer to sections in the current module
without any prefix, like Pauli suggested.  Therefore, modules in fft
can have a See Also item "fft2", "rfft".  If you want to refer across
modules, provide a prefix, e.g., "linalg.inv" (which translates to
numpy.linalg.inv).  If we can't find the function you are referring to
in the current scope,
we search upwards: file, sub-module, module.   Methods of ndarray are
referred to as `ndarray.ravel`.

The documentation is the public face of NumPy.  I ask that, if you
were one of the people involved in this discussion at the sprint, or
otherwise feel strongly about the topic, you raise your opinion now.
I'd like to settle this issue so that we can grind out many more
docstrings before the week is over.

For those of you who haven't started editing, please register at

http://sd-2116.dedibox.fr/pydocweb

The web framework is fantastic, and makes contributing a cinch.  Every
person on this list has something to contribute, and every five
minutes you donate saves another thirty.

Regards
Stéfan

2008/6/1 Pauli Virtanen <pav at iki.fi>:
> ma, 2008-05-19 kello 19:20 +0200, Stéfan van der Walt kirjoitti:
>> Hi Johann
>>
>> 2008/5/19 Johann Cohen-Tanugi <cohen at slac.stanford.edu>:
>> > yesterday when I started to modify the doctest I used import numpy. It
>> > is easy enough to change to import numpy as np, but please let's get
>> > that out of the way once and for all. I have no preference between the 2.
>>
>> Keep using numpy.func for now.  When this thread comes to a
>> conclusion, I shall do a search and replace if necessary.
>
> I took the liberty of changing this in
> http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines
> as I think this issue should be settled sometime soon as changing the
> examples later is not very productive work.
>
> It now says:
>
> - Docstring examples may assume ``import numpy`` in numpy
>  and ``import scipy`` in scipy.
>
> - ``See Also`` sections should use the full namespaced name.
>  For targets in the same module as the documented one, omitting
>  all namespace prefixes is OK, though.
>
> These choices seemed simple, understandable without knowing the
> consensus about "good import abbreviations", and avoiding the
> "from foo import *" practice.
>
> If you have objections, let's restart the discussion.
>
>        Pauli