[SciPy-dev] Namespaces in documentation

Bruce Southey bsouthey@gmail....
Mon Jun 2 08:51:33 CDT 2008

Stéfan van der Walt wrote:
> Hi Johann
> 2008/6/2 Johann Cohen-Tanugi <cohen@slac.stanford.edu>:
>> 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?
> I should rephrase: under the pylab profile, which many people use,
> numpy and pyplot will now be available as np and plt.  In addition, we
> will also provide a "numpy" profile, that  provides numpy as np.
> So a new user will
> a) Install IPython, numpy and optionally matplotlib
> b) Run "ipython -p numpy" or "ipython -pylab" (if they want to plot things)
> c) Type "cpaste" and paste in an example from the docstrings
> Regards
> Stéfan
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev@scipy.org
> http://projects.scipy.org/mailman/listinfo/scipy-dev
Why do you say '... and optionally matplotlib'?
I do not use or even known IPython but in the example Nathan provided 
you have:

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

So if it is optional, the second import will fail and so will all the rest of the code that uses 'plt'. But a user may not understand why especially if pasted in as a block of code in an shell or interactive environment (assuming that the environment does not crash). Further step 2 indicates that the import is inappropriate for IPython. 

This really illustrates the need for simple NumPy only and SciPy only self-contained examples plus these more elaborate self-contained
examples. This also ignore the issue that this is documentation about NumPy and SciPy not matplotlib and about having an graphical environment to see the plot.


More information about the Scipy-dev mailing list