[SciPy-dev] On scipy/numpy documentation, and executing code in docstrings

[Robert Kern]

On Wed, Aug 5, 2009 at 17:38, Fernando Perez<fperez.net at gmail.com> wrote:
> On Wed, Aug 5, 2009 at 1:49 PM, Emmanuelle
> Gouillart<emmanuelle.gouillart at normalesup.org> wrote:

>>> I think such a demo function could be easy to implement: just
>>> pick up the doctest lines and run them. I think a IPython
>>> extension could easily be written for this: just check what's in
>>> the ipy_*.py files under IPython/Extensions and adapt one of
>>> them.
>>
>>> There's a ready-made implementation of the doctest pickup in
>>> plot_directive.py under numpy/doc/sphinxext.
>>
>> That's exactly the kind of hints I was looking for, many thanks! I'll
>> have a look at the files you mention to see how it could be done.
>
> And when you finish, send it our way.  Operators are standing by to
> take your patch and your credit card number... :)

Something like this?

In [1]: %run_examples np.broadcast
Produce an object that mimics broadcasting.

    Parameters
    ----------
    in1, in2, ... : array_like
        Input parameters.

    Returns
    -------
    b : broadcast object
        Broadcast the input parameters against one another, and
        return an object that encapsulates the result.
        Amongst others, it has ``shape`` and ``nd`` properties, and
        may be used as an iterator.

    Examples
    --------
    Manually adding two vectors, using broadcasting:


>>> x = np.array([[1], [2], [3]])
Press <q> to quit, <Enter> to execute...

>>> y = np.array([4, 5, 6])
Press <q> to quit, <Enter> to execute...

>>> b = np.broadcast(x, y)
Press <q> to quit, <Enter> to execute...


>>> out = np.empty(b.shape)
Press <q> to quit, <Enter> to execute...

>>> out.flat = [u+v for (u,v) in b]
Press <q> to quit, <Enter> to execute...

>>> out
array([[ 5.,  6.,  7.],
       [ 6.,  7.,  8.],
       [ 7.,  8.,  9.]])

Press <q> to quit, <Enter> to execute...
 output:
array([[ 5.,  6.,  7.],
       [ 6.,  7.,  8.],
       [ 7.,  8.,  9.]])

    Compare against built-in broadcasting:


>>> x + y
array([[5, 6, 7],
       [6, 7, 8],
       [7, 8, 9]])

Press <q> to quit, <Enter> to execute...
 output:
array([[5, 6, 7],
       [6, 7, 8],
       [7, 8, 9]])

END OF DEMO
Use <demo_name>.reset() if you want to rerun it.


It uses IPython.demo. It's not especially pretty, but it's servicable.

Code is at the end of this file:

http://www.enthought.com/~rkern/cgi-bin/hgwebdir.cgi/kernmagic/file/c18f492e9688/kernmagic/mymagics.py

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless
enigma that is made terrible by our own mad attempt to interpret it as
though it had an underlying truth."
  -- Umberto Eco