DOC: Add ipython_directive to developer docs

docs/source/development/ipython_directive.txt

@@ -0,0 +1,427 b''
+.. _ipython_directive:
+
+========================
+Ipython Sphinx Directive
+========================
+
+The ipython directive is a stateful ipython shell for embedding in
+sphinx documents.  It knows about standard ipython prompts, and
+extracts the input and output lines.  These prompts will be renumbered
+starting at ``1``.  The inputs will be fed to an embedded ipython
+interpreter and the outputs from that interpreter will be inserted as
+well.  For example, code blocks like the following::
+
+  .. ipython::
+
+     In [136]: x = 2
+
+     In [137]: x**3
+     Out[137]: 8
+
+will be rendered as
+
+.. ipython::
+
+   In [136]: x = 2
+
+   In [137]: x**3
+   Out[137]: 8
+
+.. note::
+    
+   This tutorial should be read side-by-side with the Sphinx source
+   for this document because otherwise you will see only the rendered 
+   output and not the code that generated it.  Excepting the example 
+   above, we will not in general be showing the literal ReST in this 
+   document that generates the rendered output.
+   
+
+The state from previous sessions is stored, and standard error is
+trapped. At doc build time, ipython's output and std err will be
+inserted, and prompts will be renumbered. So the prompt below should
+be renumbered in the rendered docs, and pick up where the block above
+left off.
+
+.. ipython::
+
+  In [138]: z = x*3   # x is recalled from previous block
+
+  In [139]: z
+  Out[139]: 6
+
+  In [140]: print z
+  --------> print(z)
+  6
+
+  In [141]: q = z[)   # this is a syntax error -- we trap ipy exceptions
+  ------------------------------------------------------------
+     File "<ipython console>", line 1
+       q = z[)   # this is a syntax error -- we trap ipy exceptions
+	     ^
+  SyntaxError: invalid syntax
+
+
+The embedded interpreter supports some limited markup.  For example,
+you can put comments in your ipython sessions, which are reported
+verbatim.  There are some handy "pseudo-decorators" that let you
+doctest the output.  The inputs are fed to an embedded ipython
+session and the outputs from the ipython session are inserted into
+your doc.  If the output in your doc and in the ipython session don't
+match on a doctest assertion, an error will be
+
+
+.. ipython::
+
+   In [1]: x = 'hello world'
+
+   # this will raise an error if the ipython output is different
+   @doctest
+   In [2]: x.upper()
+   Out[2]: 'HELLO WORLD'
+
+   # some readline features cannot be supported, so we allow
+   # "verbatim" blocks, which are dumped in verbatim except prompts
+   # are continuously numbered
+   @verbatim
+   In [3]: x.st<TAB>
+   x.startswith  x.strip
+
+
+Multi-line input is supported. 
+
+.. ipython::
+
+   In [130]: url = 'http://ichart.finance.yahoo.com/table.csv?s=CROX\
+      .....: &d=9&e=22&f=2009&g=d&a=1&br=8&c=2006&ignore=.csv'
+
+   In [131]: print url.split('&')
+   --------> print(url.split('&'))
+   ['http://ichart.finance.yahoo.com/table.csv?s=CROX', 'd=9', 'e=22',
+
+You can do doctesting on multi-line output as well.  Just be careful
+when using non-deterministic inputs like random numbers in the ipython
+directive, because your inputs are ruin through a live interpreter, so
+if you are doctesting random output you will get an error.  Here we
+"seed" the random number generator for deterministic output, and we
+suppress the seed line so it doesn't show up in the rendered output
+
+.. ipython::
+
+   In [133]: import numpy.random
+
+   @suppress
+   In [134]: numpy.random.seed(2358)
+
+   @doctest
+   In [135]: numpy.random.rand(10,2)
+   Out[135]:
+   array([[ 0.64524308,  0.59943846],
+	  [ 0.47102322,  0.8715456 ],
+	  [ 0.29370834,  0.74776844],
+	  [ 0.99539577,  0.1313423 ],
+	  [ 0.16250302,  0.21103583],
+	  [ 0.81626524,  0.1312433 ],
+	  [ 0.67338089,  0.72302393],
+	  [ 0.7566368 ,  0.07033696],
+	  [ 0.22591016,  0.77731835],
+	  [ 0.0072729 ,  0.34273127]])
+
+
+Another demonstration of multi-line input and output
+
+.. ipython::
+
+   In [106]: print x
+   --------> print(x)
+   jdh
+
+   In [109]: for i in range(10):
+      .....:     print i
+      .....:
+      .....:
+   0
+   1
+   2
+   3
+   4
+   5
+   6
+   7
+   8
+   9
+
+
+Most of the "pseudo-decorators" can be used an options to ipython
+mode.  For example, to setup matplotlib pylab but suppress the output,
+you can do.  When using the matplotlib ``use`` directive, it should
+occur before any import of pylab.  This will not show up in the
+rendered docs, but the commands will be executed in the embedded
+interpreter and subsequent line numbers will be incremented to reflect
+the inputs::
+
+
+  .. ipython::
+     :suppress:
+
+     In [144]: from pylab import *
+
+     In [145]: ion()
+
+.. ipython::
+   :suppress:
+
+   In [144]: from pylab import *
+
+   In [145]: ion()
+
+Likewise, you can set ``:doctest:`` or ``:verbatim:`` to apply these
+settings to the entire block.  For example,
+
+.. ipython::
+   :verbatim:
+
+   In [9]: cd mpl/examples/
+   /home/jdhunter/mpl/examples
+
+   In [10]: pwd
+   Out[10]: '/home/jdhunter/mpl/examples'
+
+
+   In [14]: cd mpl/examples/<TAB>
+   mpl/examples/animation/        mpl/examples/misc/
+   mpl/examples/api/              mpl/examples/mplot3d/
+   mpl/examples/axes_grid/        mpl/examples/pylab_examples/
+   mpl/examples/event_handling/   mpl/examples/widgets
+
+   In [14]: cd mpl/examples/widgets/
+   /home/msierig/mpl/examples/widgets
+
+   In [15]: !wc *
+       2    12    77 README.txt
+      40    97   884 buttons.py
+      26    90   712 check_buttons.py
+      19    52   416 cursor.py
+     180   404  4882 menu.py
+      16    45   337 multicursor.py
+      36   106   916 radio_buttons.py
+      48   226  2082 rectangle_selector.py
+      43   118  1063 slider_demo.py
+      40   124  1088 span_selector.py
+     450  1274 12457 total
+
+You can create one or more pyplot plots and insert them with the
+``@savefig`` decorator.
+
+.. ipython::
+
+   @savefig plot_simple.png width=4in
+   In [151]: plot([1,2,3]);
+
+   # use a semicolon to suppress the output
+   @savefig hist_simple.png width=4in
+   In [151]: hist(np.random.randn(10000), 100);
+
+In a subsequent session, we can update the current figure with some
+text, and then resave 
+
+.. ipython::
+
+
+   In [151]: ylabel('number')
+
+   In [152]: title('normal distribution')
+
+   @savefig hist_with_text.png width=4in
+   In [153]: grid(True)
+
+You can also have function definitions included in the source.
+
+.. ipython::
+
+   In [3]: def square(x):   
+      ...:     """
+      ...:     An overcomplicated square function as an example.
+      ...:     """
+      ...:     if x < 0:
+      ...:         x = abs(x)
+      ...:     y = x * x
+      ...:     return y
+      ...: 
+
+Then call it from a subsequent section.
+
+.. ipython::
+
+   In [4]: square(3)
+   Out [4]: 9
+
+   In [5]: square(-2)
+   Out [5]: 4
+
+
+Writing Pure Python Code
+------------------------
+
+Pure python code is supported by the optional argument `python`. In this pure
+python syntax you do not include the output from the python interpreter. The 
+following markup::
+
+   .. ipython:: python
+      
+      foo = 'bar'
+      print foo
+      foo = 2
+      foo**2
+
+Renders as
+
+.. ipython:: python
+
+   foo = 'bar'
+   print foo
+   foo = 2
+   foo**2
+
+We can even plot from python, using the savefig decorator, as well as, suppress
+output with a semicolon
+
+.. ipython:: python
+
+   @savefig plot_simple_python.png width=4in
+   plot([1,2,3]);
+
+Similarly, std err is inserted
+
+.. ipython:: python
+
+   foo = 'bar'
+   foo[)
+
+Comments are handled and state is preserved
+
+.. ipython:: python
+
+   # comments are handled
+   print foo
+
+If you don't see the next code block then the options work.
+
+.. ipython:: python
+   :suppress:
+
+   ioff()
+   ion()
+
+Multi-line input is handled.
+
+.. ipython:: python
+
+   line = 'Multi\
+           line &\
+           support &\
+           works'
+   print line.split('&')
+
+Functions definitions are correctly parsed
+
+.. ipython:: python
+
+   def square(x):
+       """
+       An overcomplicated square function as an example.
+       """
+       if x < 0:
+           x = abs(x)
+       y = x * x
+       return y
+
+And persist across sessions
+
+.. ipython:: python
+
+   print square(3)
+   print square(-2)
+
+Pretty much anything you can do with the ipython code, you can do with
+with a simple python script. Obviously, though it doesn't make sense 
+to use the doctest option.
+
+Pseudo-Decorators
+=================
+
+Here are the supported decorators, and any optional arguments they
+take.  Some of the decorators can be used as options to the entire
+block (eg ``verbatim`` and ``suppress``), and some only apply to the
+line just below them (eg ``savefig``).
+
+@suppress
+
+    execute the ipython input block, but suppress the input and output
+    block from the rendered output.  Also, can be applied to the entire
+    ``..ipython`` block as a directive option with ``:suppress:``.
+
+@verbatim
+
+    insert the input and output block in verbatim, but auto-increment
+    the line numbers. Internally, the interpreter will be fed an empty
+    string, so it is a no-op that keeps line numbering consistent.
+    Also, can be applied to the entire ``..ipython`` block as a
+    directive option with ``:verbatim:``.
+
+@savefig OUTFILE [IMAGE_OPTIONS]
+
+    save the figure to the static directory and insert it into the
+    document, possibly binding it into a minipage and/or putting
+    code/figure label/references to associate the code and the
+    figure. Takes args to pass to the image directive (*scale*,
+    *width*, etc can be kwargs); see `image options
+    <http://docutils.sourceforge.net/docs/ref/rst/directives.html#image>`_
+    for details.
+
+@doctest
+
+    Compare the pasted in output in the ipython block with the output
+    generated at doc build time, and raise errors if they don’t
+    match. Also, can be applied to the entire ``..ipython`` block as a
+    directive option with ``:doctest:``.
+
+Configuration Options
+=====================
+
+ipython_savefig_dir
+
+    The directory in which to save the figures. This is relative to the
+    Sphinx source directory. The default is `html_static_path`.
+
+ipython_rgxin
+
+    The compiled regular expression to denote the start of IPython input 
+    lines. The default is re.compile('In \[(\d+)\]:\s?(.*)\s*'). You 
+    shouldn't need to change this.
+
+ipython_rgxout
+
+    The compiled regular expression to denote the start of IPython output 
+    lines. The default is re.compile('Out\[(\d+)\]:\s?(.*)\s*'). You 
+    shouldn't need to change this.
+
+
+ipython_promptin
+
+    The string to represent the IPython input prompt in the generated ReST. 
+    The default is 'In [%d]:'. This expects that the line numbers are used
+    in the prompt.
+
+ipython_promptout
+
+    The string to represent the IPython prompt in the generated ReST. The
+    default is 'Out [%d]:'. This expects that the line numbers are used
+    in the prompt.
+
+.. _ipython_literal:
+
+Sphinx source for this tutorial
+===============================
+
+.. literalinclude:: ipython_directive.rst
+

docs/source/conf.py

@@ -43,6 +43,7 b' extensions = ['
     'sphinx.ext.doctest',
     'inheritance_diagram',
     'ipython_console_highlighting',
+    'ipython_directive',
     'numpydoc',  # to preprocess docstrings
     'github',  # for easy GitHub links
 ]

docs/source/development/index.txt

@@ -23,3 +23,4 b" IPython developer's guide"
    ipython_qt.txt
    ipythonzmq.txt
    notebook_todo.txt
+   ipython_directive.txt