headers
Pauli Virtanen | 1 Jun 02:55
Picon
Picon
Favicon

Re: Namespaces in documentation (was: ANN: NumPy/SciPy Documentation Marathon 2008)

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.
(Continue reading)

Permalink | Reply | 17 comments |
headers
Stéfan van der Walt | 1 Jun 23:39
Picon
Picon
Favicon

Re: Namespaces in documentation (was: ANN: NumPy/SciPy Documentation Marathon 2008)

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
(Continue reading)

Permalink | Reply | 16 comments |
headers
Alan Jackson | 2 Jun 03:27

docstring sd-2116.dedibox.fr problem

I can view the docstrings, but I can no longer preview or save them.

I eventually get a timeout.

--

-- 
-----------------------------------------------------------------------
| Alan K. Jackson            | To see a World in a Grain of Sand      |
| alan <at> ajackson.org          | And a Heaven in a Wild Flower,         |
| www.ajackson.org           | Hold Infinity in the palm of your hand |
| Houston, Texas             | And Eternity in an hour. - Blake       |
-----------------------------------------------------------------------
Permalink | Reply | 2 comments |
headers
Johann Cohen-Tanugi | 2 Jun 10:23
Picon
Favicon

Re: Namespaces in documentation

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
(Continue reading)

Permalink | Reply | 15 comments |
headers
Stéfan van der Walt | 2 Jun 10:33
Picon
Picon
Favicon

Re: docstring sd-2116.dedibox.fr problem

Hi Alan

Thank you for bringing this to our attention.  We should have the
problem sorted out by this afternoon.

Sorry for any inconvenience caused!

Regards
Stéfan

2008/6/2 Alan Jackson <alan <at> ajackson.org>:
> I can view the docstrings, but I can no longer preview or save them.
>
> I eventually get a timeout.
Permalink | Reply | 0 comments |
headers
Stéfan van der Walt | 2 Jun 10:53
Picon
Picon
Favicon

Re: Namespaces in documentation

Hi Johann

2008/6/2 Johann Cohen-Tanugi <cohen <at> 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
Permalink | Reply | 14 comments |
headers
Johann Cohen-Tanugi | 2 Jun 10:47
Picon
Favicon

Re: Namespaces in documentation

ok, the new numpy profile was the missing piece of info :)
Anyway, +1 for np/sp in docstrings.
Johann

Stéfan van der Walt wrote:
> Hi Johann
>
> 2008/6/2 Johann Cohen-Tanugi <cohen <at> 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
(Continue reading)

Permalink | Reply | 8 comments |
headers
Bruce Southey | 2 Jun 15:51
Picon

Re: Namespaces in documentation

Stéfan van der Walt wrote:
> Hi Johann
>
> 2008/6/2 Johann Cohen-Tanugi <cohen <at> 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 <at> scipy.org
> http://projects.scipy.org/mailman/listinfo/scipy-dev
>
>
(Continue reading)

Permalink | Reply | 4 comments |
headers
Johann Cohen-Tanugi | 2 Jun 16:05
Picon
Favicon

Re: Namespaces in documentation

I think that what Stefan meant is either
1) you have ipython/numpy and then you would run ipython -numpy
2) or optionally you also have matplotlib and then you would run ipython 
-pylab

and in *both* cases the cpaste of the docstrings exemple will work.
hth,
Johann

Bruce Southey wrote:
> Stéfan van der Walt wrote:
>   
>> Hi Johann
>>
>> 2008/6/2 Johann Cohen-Tanugi <cohen <at> 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
>>
(Continue reading)

Permalink | Reply | 0 comments |
headers
Stéfan van der Walt | 2 Jun 17:09
Picon
Picon
Favicon

Re: Namespaces in documentation

Hi Bruce

2008/6/2 Bruce Southey <bsouthey <at> gmail.com>:
> 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.

Each function has examples that do not require matplotlib.  The
plotted examples are used in addition to illuminate its working.

Regards
Stéfan
Permalink | Reply | 2 comments |

Gmane