Skip to content

Commit 70f7888

Browse files
dhermesdhermes
committed
Many small fixes to ipython_directive.rst.
Including: - Typo fixes (e.g. "Sphinc" -> "Sphinx", "ruin" -> "run", etc.) - Python 3 errors with `print` used as a keyword vs. function - Changing line numbers to start at 1 locally within an `ipython` directive block (because they get renumbered anyhow) - Normalizing all usage of IPython and Sphinx (some places were lowercased, e.g. "ipython" and "sphinx") - Converting tabs to spaces (tabs seemed inadvertent) - Removing comments that have no effect on the block (output is only checked by `doctest` and only displayed during `verbatim`) - "Standardizing" the number of empty lines between sections - Adding whitespace between operators / commas (per PEP8) - Using implicit string concat rather than \-continuation - Using codefont (via double backticks) for pseudo-decorator sections - Adding "Enabling IPython Directive" section which explains which Sphinx extensions enable this behavior
1 parent 7eff0c5 commit 70f7888

1 file changed

Lines changed: 87 additions & 105 deletions

File tree

‎ipython_directive.rst‎

Lines changed: 87 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
.. _ipython_directive:
22

33
=================
4-
Ipython Directive
4+
IPython Directive
55
=================
66

7-
The ipython directive is a stateful ipython shell for embedding in
8-
sphinx documents. It knows about standard ipython prompts, and
7+
The IPython directive is a stateful IPython shell for embedding in
8+
Sphinx documents. It knows about standard IPython prompts, and
99
extracts the input and output lines. These prompts will be renumbered
10-
starting at ``1``. The inputs will be fed to an embedded ipython
10+
starting at ``1``. The inputs will be fed to an embedded IPython
1111
interpreter and the outputs from that interpreter will be inserted as
1212
well. For example, code blocks like the following::
1313

@@ -29,53 +29,43 @@ will be rendered as
2929

3030
.. note::
3131

32-
This tutorial should be read side-by-side with the Sphinc source
32+
This tutorial should be read side-by-side with the Sphinx source
3333
for this document (see :ref:`ipython_literal`) because otherwise
3434
you will see only the rendered output and not the code that
3535
generated it. Excepting the example above, we will not in general
36-
be showing the liuteral rest in this document that generates the
36+
be showing the literal ReST in this document that generates the
3737
rendered output.
3838

3939

4040
The state from previous sessions is stored, and standard error is
41-
trapped. At doc build time, ipython's output and std err will be
41+
trapped. At doc build time, IPython's output and std err will be
4242
inserted, and prompts will be renumbered. So the prompt below should
4343
be renumbered in the rendered docs, and pick up where the block above
4444
left off.
4545

4646
.. ipython::
4747

48-
In [138]: z = x*3 # x is recalled from previous block
48+
In [1]: z = x * 3 # x is recalled from previous block
4949

50-
In [139]: z
51-
Out[139]: 6
50+
In [2]: z
5251

53-
In [140]: print z
54-
--------> print(z)
55-
6
56-
57-
In [141]: q = z[) # this is a syntax error -- we trap ipy exceptions
58-
------------------------------------------------------------
59-
File "<ipython console>", line 1
60-
q = z[) # this is a syntax error -- we trap ipy exceptions
61-
^
62-
SyntaxError: invalid syntax
52+
In [3]: print(z)
6353

54+
In [4]: q = z[) # this is a syntax error -- we trap exceptions
6455

6556
The embedded interpreter supports some limited markup. For example,
66-
you can put comments in your ipython sessions, which are reported
57+
you can put comments in your IPython sessions, which are reported
6758
verbatim. There are some handy "pseudo-decorators" that let you
68-
doctest the output. The inputs are fed to an embedded ipython
69-
session and the outputs from the ipython session are inserted into
70-
your doc. If the output in your doc and in the ipython session don't
71-
match on a doctest assertion, an error will be
72-
59+
doctest the output. The inputs are fed to an embedded IPython
60+
session and the outputs from the IPython session are inserted into
61+
your doc. If the output in your doc and in the IPython session don't
62+
match on a doctest assertion, an error will be raised
7363

7464
.. ipython::
7565

7666
In [1]: x = 'hello world'
7767

78-
# this will raise an error if the ipython output is different
68+
# this will raise an error if the IPython output is different
7969
@doctest
8070
In [2]: x.upper()
8171
Out[2]: 'HELLO WORLD'
@@ -87,79 +77,60 @@ match on a doctest assertion, an error will be
8777
In [3]: x.st<TAB>
8878
x.startswith x.strip
8979

90-
9180
Multi-line input is supported.
9281

9382
.. ipython::
9483

95-
In [130]: url = 'http://ichart.finance.yahoo.com/table.csv?s=CROX\
96-
.....: &d=9&e=22&f=2009&g=d&a=1&br=8&c=2006&ignore=.csv'
97-
98-
In [131]: print url.split('&')
99-
--------> print(url.split('&'))
100-
['http://ichart.finance.yahoo.com/table.csv?s=CROX', 'd=9', 'e=22',
101-
'f=2009', 'g=d', 'a=1', 'b=8', 'c=2006', 'ignore=.csv']
84+
In [1]: url = ('https://example.com?s=CROX&d=9&e=22&f=2009&'
85+
...: 'g=d&a=1&br=8&c=2006&ignore=.csv')
86+
...:
10287

103-
In [60]: import urllib
88+
In [2]: print(url.split('&'))
10489

90+
In [3]: import urllib
10591

10692
You can do doctesting on multi-line output as well. Just be careful
107-
when using non-deterministic inputs like random numbers in the ipython
108-
directive, because your inputs are ruin through a live interpreter, so
93+
when using non-deterministic inputs like random numbers in the IPython
94+
directive, because your inputs are run through a live interpreter, so
10995
if you are doctesting random output you will get an error. Here we
11096
"seed" the random number generator for deterministic output, and we
11197
suppress the seed line so it doesn't show up in the rendered output
11298

11399
.. ipython::
114100

115-
In [133]: import numpy.random
101+
In [1]: import numpy.random
116102

117103
@suppress
118-
In [134]: numpy.random.seed(2358)
104+
In [2]: numpy.random.seed(2358)
119105

120106
@doctest
121-
In [135]: numpy.random.rand(10,2)
122-
Out[135]:
107+
In [3]: numpy.random.rand(10, 2)
108+
Out[3]:
123109
array([[ 0.64524308, 0.59943846],
124-
[ 0.47102322, 0.8715456 ],
125-
[ 0.29370834, 0.74776844],
126-
[ 0.99539577, 0.1313423 ],
127-
[ 0.16250302, 0.21103583],
128-
[ 0.81626524, 0.1312433 ],
129-
[ 0.67338089, 0.72302393],
130-
[ 0.7566368 , 0.07033696],
131-
[ 0.22591016, 0.77731835],
132-
[ 0.0072729 , 0.34273127]])
133-
110+
[ 0.47102322, 0.8715456 ],
111+
[ 0.29370834, 0.74776844],
112+
[ 0.99539577, 0.1313423 ],
113+
[ 0.16250302, 0.21103583],
114+
[ 0.81626524, 0.1312433 ],
115+
[ 0.67338089, 0.72302393],
116+
[ 0.7566368 , 0.07033696],
117+
[ 0.22591016, 0.77731835],
118+
[ 0.0072729 , 0.34273127]])
134119

135120
Another demonstration of multi-line input and output
136121

137122
.. ipython::
138123

139-
In [106]: print x
140-
--------> print(x)
141-
jdh
142-
143-
In [109]: for i in range(10):
144-
.....: print i
145-
.....:
146-
.....:
147-
0
148-
1
149-
2
150-
3
151-
4
152-
5
153-
6
154-
7
155-
8
156-
9
157-
158-
159-
Most of the "pseudo-decorators" can be used an options to ipython
160-
mode. For example, to setup matplotlib pylab but suppress the output,
124+
In [1]: print(x)
125+
126+
In [2]: for i in range(10):
127+
...: print(i)
128+
...:
129+
130+
Most of the "pseudo-decorators" can be used as options to IPython
131+
mode. For example, to setup ``matplotlib`` / ``pylab`` but suppress the output,
161132
you can do. When using the matplotlib ``use`` directive, it should
162-
occur before any import of pylab. This will not show up in the
133+
occur before any import of ``pylab``. This will not show up in the
163134
rendered docs, but the commands will be executed in the embedded
164135
interpreter and subsequent line numbers will be incremented to reflect
165136
the inputs::
@@ -168,40 +139,39 @@ the inputs::
168139
.. ipython::
169140
:suppress:
170141

171-
In [144]: from pylab import *
142+
In [1]: from pylab import *
172143

173-
In [145]: ion()
144+
In [2]: ion()
174145

175146
.. ipython::
176147
:suppress:
177148

178-
In [144]: from pylab import *
149+
In [1]: from pylab import *
179150

180-
In [145]: ion()
151+
In [2]: ion()
181152

182-
Likewise, you can set ``:doctest:`` or ``:verbatim:`` to apply these
183-
settings to the entire block. For example,
153+
Likewise, you can set the ``:doctest:`` or ``:verbatim:`` Sphinx options to
154+
apply these settings to the entire block. For example,
184155

185156
.. ipython::
186157
:verbatim:
187158

188-
In [9]: cd mpl/examples/
159+
In [1]: cd mpl/examples/
189160
/home/jdhunter/mpl/examples
190161

191-
In [10]: pwd
192-
Out[10]: '/home/jdhunter/mpl/examples'
193-
162+
In [2]: pwd
163+
Out[2]: '/home/jdhunter/mpl/examples'
194164

195-
In [14]: cd mpl/examples/<TAB>
165+
In [3]: cd mpl/examples/<TAB>
196166
mpl/examples/animation/ mpl/examples/misc/
197167
mpl/examples/api/ mpl/examples/mplot3d/
198168
mpl/examples/axes_grid/ mpl/examples/pylab_examples/
199169
mpl/examples/event_handling/ mpl/examples/widgets
200170

201-
In [14]: cd mpl/examples/widgets/
171+
In [4]: cd mpl/examples/widgets/
202172
/home/jdhunter/mpl/examples/widgets
203173

204-
In [15]: !wc *
174+
In [5]: !wc *
205175
2 12 77 README.txt
206176
40 97 884 buttons.py
207177
26 90 712 check_buttons.py
@@ -214,32 +184,29 @@ settings to the entire block. For example,
214184
40 124 1088 span_selector.py
215185
450 1274 12457 total
216186

217-
218-
219-
You can create one or more pyplot plots and insert them with the
187+
You can create one or more plots and insert them with the
220188
``@savefig`` decorator.
221189

222190
.. ipython::
223191

224192
@savefig plot_simple.png width=4in
225-
In [151]: plot([1,2,3]);
193+
In [1]: plot([1,2,3]);
226194

227195
# use a semicolon to suppress the output
228196
@savefig hist_simple.png width=4in
229-
In [151]: hist(np.random.randn(10000), 100);
197+
In [2]: hist(np.random.randn(10000), 100);
230198

231199
In a subsequent session, we can update the current figure with some
232200
text, and then resave
233201

234202
.. ipython::
235203

204+
In [1]: ylabel('number')
236205

237-
In [151]: ylabel('number')
206+
In [2]: title('normal distribution')
238207

239-
In [152]: title('normal distribution')
240-
241-
@savefig hist_with_text.png width=4in
242-
In [153]: grid(True)
208+
@savefig hist_with_text.png width=4in align=center
209+
In [3]: grid(True)
243210

244211
Pseudo-Decorators
245212
=================
@@ -249,21 +216,21 @@ take. Some of the decorators can be used as options to the entire
249216
block (eg ``verbatim`` and ``suppress``), and some only apply to the
250217
line just below them (eg ``savefig``).
251218

252-
@suppress
219+
``@suppress``
253220

254-
execute the ipython input block, but suppress the input and output
221+
execute the IPython input block, but suppress the input and output
255222
block from the rendered output. Also, can be applied to the entire
256223
``..ipython`` block as a directive option with ``:suppress:``.
257224

258-
@verbatim
225+
``@verbatim``
259226

260227
insert the input and output block in verbatim, but auto-increment
261228
the line numbers. Internally, the interpreter will be fed an empty
262229
string, so it is a no-op that keeps line numbering consistent.
263230
Also, can be applied to the entire ``..ipython`` block as a
264231
directive option with ``:verbatim:``.
265232

266-
@savefig OUTFILE [IMAGE_OPTIONS]
233+
``@savefig OUTFILE [IMAGE_OPTIONS]``
267234

268235
save the figure to the static directory and insert it into the
269236
document, possibly binding it into a minipage and/or putting
@@ -273,16 +240,31 @@ line just below them (eg ``savefig``).
273240
<http://docutils.sourceforge.net/docs/ref/rst/directives.html#image>`_
274241
for details.
275242

276-
@doctest
243+
``@doctest``
277244

278-
Compare the pasted in output in the ipython block with the output
245+
Compare the pasted in output in the IPython block with the output
279246
generated at doc build time, and raise errors if they don’t
280247
match. Also, can be applied to the entire ``..ipython`` block as a
281248
directive option with ``:doctest:``.
282249

250+
Enabling IPython Directive
251+
==========================
252+
253+
To enable the IPython directive(s) in your Sphinx documentation,
254+
you'll need to have ``IPython`` installed and include the following
255+
in your Sphinx configuration (``conf.py``):
256+
257+
.. code-block:: python
258+
259+
extensions = [
260+
'IPython.sphinxext.ipython_directive',
261+
'IPython.sphinxext.ipython_console_highlighting',
262+
...
263+
]
264+
283265
.. _ipython_literal:
284266

285267
Sphinx source for this tutorial
286-
====================================
268+
===============================
287269

288270
.. literalinclude:: ipython_directive.rst

0 commit comments

Comments
 (0)