[SciPy-dev] Namespaces in documentation

[Johann Cohen-Tanugi]

hi there,

Stéfan van der Walt wrote:
> 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.
>
>   
1) I think that I would also prefer np to the full numpy. I have been 
editing some docstrings and sometimes I feel that "numpy." clutters the 
easy reading of the example a bit too much
2) On the other hand, I must have missed something about the ipython 
patch : using the -pylab profile isn't going to mean that people must 
have matplotlib installed in order to cut-and-paste the docstring 
examples? That would seem counter-intuitive at best! As a matter of 
fact, why does it have to live in the pylab profile?

best,
JCT

> 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
>>     
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev at scipy.org
> http://projects.scipy.org/mailman/listinfo/scipy-dev
>