Show More
@@ -0,0 +1,435 b'' | |||||
|
1 | ||||
|
2 | .. _ipython_directive: | |||
|
3 | ||||
|
4 | ======================== | |||
|
5 | IPython Sphinx Directive | |||
|
6 | ======================== | |||
|
7 | ||||
|
8 | .. note:: | |||
|
9 | ||||
|
10 | This has been salvadged from history, so information may be approximate or | |||
|
11 | duplicated. Fixes welcome. | |||
|
12 | ||||
|
13 | The ipython directive is a stateful ipython shell for embedding in | |||
|
14 | sphinx documents. It knows about standard ipython prompts, and | |||
|
15 | extracts the input and output lines. These prompts will be renumbered | |||
|
16 | starting at ``1``. The inputs will be fed to an embedded ipython | |||
|
17 | interpreter and the outputs from that interpreter will be inserted as | |||
|
18 | well. For example, code blocks like the following:: | |||
|
19 | ||||
|
20 | .. ipython:: | |||
|
21 | ||||
|
22 | In [136]: x = 2 | |||
|
23 | ||||
|
24 | In [137]: x**3 | |||
|
25 | Out[137]: 8 | |||
|
26 | ||||
|
27 | will be rendered as | |||
|
28 | ||||
|
29 | .. ipython:: | |||
|
30 | ||||
|
31 | In [136]: x = 2 | |||
|
32 | ||||
|
33 | In [137]: x**3 | |||
|
34 | Out[137]: 8 | |||
|
35 | ||||
|
36 | .. note:: | |||
|
37 | ||||
|
38 | This tutorial should be read side-by-side with the Sphinx source | |||
|
39 | for this document because otherwise you will see only the rendered | |||
|
40 | output and not the code that generated it. Excepting the example | |||
|
41 | above, we will not in general be showing the literal ReST in this | |||
|
42 | document that generates the rendered output. | |||
|
43 | ||||
|
44 | ||||
|
45 | The state from previous sessions is stored, and standard error is | |||
|
46 | trapped. At doc build time, ipython's output and std err will be | |||
|
47 | inserted, and prompts will be renumbered. So the prompt below should | |||
|
48 | be renumbered in the rendered docs, and pick up where the block above | |||
|
49 | left off. | |||
|
50 | ||||
|
51 | .. ipython:: | |||
|
52 | :verbatim: | |||
|
53 | ||||
|
54 | In [138]: z = x*3 # x is recalled from previous block | |||
|
55 | ||||
|
56 | In [139]: z | |||
|
57 | Out[139]: 6 | |||
|
58 | ||||
|
59 | In [142]: print z | |||
|
60 | --------> print(z) | |||
|
61 | 6 | |||
|
62 | ||||
|
63 | In [141]: q = z[) # this is a syntax error -- we trap ipy exceptions | |||
|
64 | ------------------------------------------------------------ | |||
|
65 | File "<ipython console>", line 1 | |||
|
66 | q = z[) # this is a syntax error -- we trap ipy exceptions | |||
|
67 | ^ | |||
|
68 | SyntaxError: invalid syntax | |||
|
69 | ||||
|
70 | ||||
|
71 | The embedded interpreter supports some limited markup. For example, | |||
|
72 | you can put comments in your ipython sessions, which are reported | |||
|
73 | verbatim. There are some handy "pseudo-decorators" that let you | |||
|
74 | doctest the output. The inputs are fed to an embedded ipython | |||
|
75 | session and the outputs from the ipython session are inserted into | |||
|
76 | your doc. If the output in your doc and in the ipython session don't | |||
|
77 | match on a doctest assertion, an error will be | |||
|
78 | ||||
|
79 | ||||
|
80 | .. ipython:: | |||
|
81 | ||||
|
82 | In [1]: x = 'hello world' | |||
|
83 | ||||
|
84 | # this will raise an error if the ipython output is different | |||
|
85 | @doctest | |||
|
86 | In [2]: x.upper() | |||
|
87 | Out[2]: 'HELLO WORLD' | |||
|
88 | ||||
|
89 | # some readline features cannot be supported, so we allow | |||
|
90 | # "verbatim" blocks, which are dumped in verbatim except prompts | |||
|
91 | # are continuously numbered | |||
|
92 | @verbatim | |||
|
93 | In [3]: x.st<TAB> | |||
|
94 | x.startswith x.strip | |||
|
95 | ||||
|
96 | ||||
|
97 | Multi-line input is supported. | |||
|
98 | ||||
|
99 | .. ipython:: | |||
|
100 | :verbatim: | |||
|
101 | ||||
|
102 | In [130]: url = 'http://ichart.finance.yahoo.com/table.csv?s=CROX\ | |||
|
103 | .....: &d=9&e=22&f=2009&g=d&a=1&br=8&c=2006&ignore=.csv' | |||
|
104 | ||||
|
105 | In [131]: print url.split('&') | |||
|
106 | --------> print(url.split('&')) | |||
|
107 | ['http://ichart.finance.yahoo.com/table.csv?s=CROX', 'd=9', 'e=22', | |||
|
108 | ||||
|
109 | You can do doctesting on multi-line output as well. Just be careful | |||
|
110 | when using non-deterministic inputs like random numbers in the ipython | |||
|
111 | directive, because your inputs are ruin through a live interpreter, so | |||
|
112 | if you are doctesting random output you will get an error. Here we | |||
|
113 | "seed" the random number generator for deterministic output, and we | |||
|
114 | suppress the seed line so it doesn't show up in the rendered output | |||
|
115 | ||||
|
116 | .. ipython:: | |||
|
117 | ||||
|
118 | In [133]: import numpy.random | |||
|
119 | ||||
|
120 | @suppress | |||
|
121 | In [134]: numpy.random.seed(2358) | |||
|
122 | ||||
|
123 | @doctest | |||
|
124 | In [135]: numpy.random.rand(10,2) | |||
|
125 | Out[135]: | |||
|
126 | array([[0.64524308, 0.59943846], | |||
|
127 | [0.47102322, 0.8715456 ], | |||
|
128 | [0.29370834, 0.74776844], | |||
|
129 | [0.99539577, 0.1313423 ], | |||
|
130 | [0.16250302, 0.21103583], | |||
|
131 | [0.81626524, 0.1312433 ], | |||
|
132 | [0.67338089, 0.72302393], | |||
|
133 | [0.7566368 , 0.07033696], | |||
|
134 | [0.22591016, 0.77731835], | |||
|
135 | [0.0072729 , 0.34273127]]) | |||
|
136 | ||||
|
137 | ||||
|
138 | Another demonstration of multi-line input and output | |||
|
139 | ||||
|
140 | .. ipython:: | |||
|
141 | :verbatim: | |||
|
142 | ||||
|
143 | In [106]: print x | |||
|
144 | --------> print(x) | |||
|
145 | jdh | |||
|
146 | ||||
|
147 | In [109]: for i in range(10): | |||
|
148 | .....: print i | |||
|
149 | .....: | |||
|
150 | .....: | |||
|
151 | 0 | |||
|
152 | 1 | |||
|
153 | 2 | |||
|
154 | 3 | |||
|
155 | 4 | |||
|
156 | 5 | |||
|
157 | 6 | |||
|
158 | 7 | |||
|
159 | 8 | |||
|
160 | 9 | |||
|
161 | ||||
|
162 | ||||
|
163 | Most of the "pseudo-decorators" can be used an options to ipython | |||
|
164 | mode. For example, to setup matplotlib pylab but suppress the output, | |||
|
165 | you can do. When using the matplotlib ``use`` directive, it should | |||
|
166 | occur before any import of pylab. This will not show up in the | |||
|
167 | rendered docs, but the commands will be executed in the embedded | |||
|
168 | interpreter and subsequent line numbers will be incremented to reflect | |||
|
169 | the inputs:: | |||
|
170 | ||||
|
171 | ||||
|
172 | .. ipython:: | |||
|
173 | :suppress: | |||
|
174 | ||||
|
175 | In [144]: from pylab import * | |||
|
176 | ||||
|
177 | In [145]: ion() | |||
|
178 | ||||
|
179 | .. ipython:: | |||
|
180 | :suppress: | |||
|
181 | ||||
|
182 | In [144]: from pylab import * | |||
|
183 | ||||
|
184 | In [145]: ion() | |||
|
185 | ||||
|
186 | Likewise, you can set ``:doctest:`` or ``:verbatim:`` to apply these | |||
|
187 | settings to the entire block. For example, | |||
|
188 | ||||
|
189 | .. ipython:: | |||
|
190 | :verbatim: | |||
|
191 | ||||
|
192 | In [9]: cd mpl/examples/ | |||
|
193 | /home/jdhunter/mpl/examples | |||
|
194 | ||||
|
195 | In [10]: pwd | |||
|
196 | Out[10]: '/home/jdhunter/mpl/examples' | |||
|
197 | ||||
|
198 | ||||
|
199 | In [14]: cd mpl/examples/<TAB> | |||
|
200 | mpl/examples/animation/ mpl/examples/misc/ | |||
|
201 | mpl/examples/api/ mpl/examples/mplot3d/ | |||
|
202 | mpl/examples/axes_grid/ mpl/examples/pylab_examples/ | |||
|
203 | mpl/examples/event_handling/ mpl/examples/widgets | |||
|
204 | ||||
|
205 | In [14]: cd mpl/examples/widgets/ | |||
|
206 | /home/msierig/mpl/examples/widgets | |||
|
207 | ||||
|
208 | In [15]: !wc * | |||
|
209 | 2 12 77 README.txt | |||
|
210 | 40 97 884 buttons.py | |||
|
211 | 26 90 712 check_buttons.py | |||
|
212 | 19 52 416 cursor.py | |||
|
213 | 180 404 4882 menu.py | |||
|
214 | 16 45 337 multicursor.py | |||
|
215 | 36 106 916 radio_buttons.py | |||
|
216 | 48 226 2082 rectangle_selector.py | |||
|
217 | 43 118 1063 slider_demo.py | |||
|
218 | 40 124 1088 span_selector.py | |||
|
219 | 450 1274 12457 total | |||
|
220 | ||||
|
221 | You can create one or more pyplot plots and insert them with the | |||
|
222 | ``@savefig`` decorator. | |||
|
223 | ||||
|
224 | .. ipython:: | |||
|
225 | ||||
|
226 | @savefig plot_simple.png width=4in | |||
|
227 | In [151]: plot([1,2,3]); | |||
|
228 | ||||
|
229 | # use a semicolon to suppress the output | |||
|
230 | @savefig hist_simple.png width=4in | |||
|
231 | In [151]: hist(np.random.randn(10000), 100); | |||
|
232 | ||||
|
233 | In a subsequent session, we can update the current figure with some | |||
|
234 | text, and then resave | |||
|
235 | ||||
|
236 | .. ipython:: | |||
|
237 | ||||
|
238 | ||||
|
239 | In [151]: ylabel('number') | |||
|
240 | ||||
|
241 | In [152]: title('normal distribution') | |||
|
242 | ||||
|
243 | @savefig hist_with_text.png width=4in | |||
|
244 | In [153]: grid(True) | |||
|
245 | ||||
|
246 | You can also have function definitions included in the source. | |||
|
247 | ||||
|
248 | .. ipython:: | |||
|
249 | ||||
|
250 | In [3]: def square(x): | |||
|
251 | ...: """ | |||
|
252 | ...: An overcomplicated square function as an example. | |||
|
253 | ...: """ | |||
|
254 | ...: if x < 0: | |||
|
255 | ...: x = abs(x) | |||
|
256 | ...: y = x * x | |||
|
257 | ...: return y | |||
|
258 | ...: | |||
|
259 | ||||
|
260 | Then call it from a subsequent section. | |||
|
261 | ||||
|
262 | .. ipython:: | |||
|
263 | ||||
|
264 | In [4]: square(3) | |||
|
265 | Out [4]: 9 | |||
|
266 | ||||
|
267 | In [5]: square(-2) | |||
|
268 | Out [5]: 4 | |||
|
269 | ||||
|
270 | ||||
|
271 | Writing Pure Python Code | |||
|
272 | ------------------------ | |||
|
273 | ||||
|
274 | Pure python code is supported by the optional argument `python`. In this pure | |||
|
275 | python syntax you do not include the output from the python interpreter. The | |||
|
276 | following markup:: | |||
|
277 | ||||
|
278 | .. ipython:: python | |||
|
279 | ||||
|
280 | foo = 'bar' | |||
|
281 | print(foo) | |||
|
282 | foo = 2 | |||
|
283 | foo**2 | |||
|
284 | ||||
|
285 | Renders as | |||
|
286 | ||||
|
287 | .. ipython:: python | |||
|
288 | ||||
|
289 | foo = 'bar' | |||
|
290 | print(foo) | |||
|
291 | foo = 2 | |||
|
292 | foo**2 | |||
|
293 | ||||
|
294 | We can even plot from python, using the savefig decorator, as well as, suppress | |||
|
295 | output with a semicolon | |||
|
296 | ||||
|
297 | .. ipython:: python | |||
|
298 | ||||
|
299 | @savefig plot_simple_python.png width=4in | |||
|
300 | plot([1,2,3]); | |||
|
301 | ||||
|
302 | Similarly, std err is inserted | |||
|
303 | ||||
|
304 | .. ipython:: python | |||
|
305 | :okexcept: | |||
|
306 | ||||
|
307 | foo = 'bar' | |||
|
308 | foo[) | |||
|
309 | ||||
|
310 | Comments are handled and state is preserved | |||
|
311 | ||||
|
312 | .. ipython:: python | |||
|
313 | ||||
|
314 | # comments are handled | |||
|
315 | print(foo) | |||
|
316 | ||||
|
317 | If you don't see the next code block then the options work. | |||
|
318 | ||||
|
319 | .. ipython:: python | |||
|
320 | :suppress: | |||
|
321 | ||||
|
322 | ioff() | |||
|
323 | ion() | |||
|
324 | ||||
|
325 | Multi-line input is handled. | |||
|
326 | ||||
|
327 | .. ipython:: python | |||
|
328 | ||||
|
329 | line = 'Multi\ | |||
|
330 | line &\ | |||
|
331 | support &\ | |||
|
332 | works' | |||
|
333 | print(line.split('&')) | |||
|
334 | ||||
|
335 | Functions definitions are correctly parsed | |||
|
336 | ||||
|
337 | .. ipython:: python | |||
|
338 | ||||
|
339 | def square(x): | |||
|
340 | """ | |||
|
341 | An overcomplicated square function as an example. | |||
|
342 | """ | |||
|
343 | if x < 0: | |||
|
344 | x = abs(x) | |||
|
345 | y = x * x | |||
|
346 | return y | |||
|
347 | ||||
|
348 | And persist across sessions | |||
|
349 | ||||
|
350 | .. ipython:: python | |||
|
351 | ||||
|
352 | print(square(3)) | |||
|
353 | print(square(-2)) | |||
|
354 | ||||
|
355 | Pretty much anything you can do with the ipython code, you can do with | |||
|
356 | with a simple python script. Obviously, though it doesn't make sense | |||
|
357 | to use the doctest option. | |||
|
358 | ||||
|
359 | Pseudo-Decorators | |||
|
360 | ================= | |||
|
361 | ||||
|
362 | Here are the supported decorators, and any optional arguments they | |||
|
363 | take. Some of the decorators can be used as options to the entire | |||
|
364 | block (eg ``verbatim`` and ``suppress``), and some only apply to the | |||
|
365 | line just below them (eg ``savefig``). | |||
|
366 | ||||
|
367 | @suppress | |||
|
368 | ||||
|
369 | execute the ipython input block, but suppress the input and output | |||
|
370 | block from the rendered output. Also, can be applied to the entire | |||
|
371 | ``.. ipython`` block as a directive option with ``:suppress:``. | |||
|
372 | ||||
|
373 | @verbatim | |||
|
374 | ||||
|
375 | insert the input and output block in verbatim, but auto-increment | |||
|
376 | the line numbers. Internally, the interpreter will be fed an empty | |||
|
377 | string, so it is a no-op that keeps line numbering consistent. | |||
|
378 | Also, can be applied to the entire ``.. ipython`` block as a | |||
|
379 | directive option with ``:verbatim:``. | |||
|
380 | ||||
|
381 | @savefig OUTFILE [IMAGE_OPTIONS] | |||
|
382 | ||||
|
383 | save the figure to the static directory and insert it into the | |||
|
384 | document, possibly binding it into a minipage and/or putting | |||
|
385 | code/figure label/references to associate the code and the | |||
|
386 | figure. Takes args to pass to the image directive (*scale*, | |||
|
387 | *width*, etc can be kwargs); see `image options | |||
|
388 | <http://docutils.sourceforge.net/docs/ref/rst/directives.html#image>`_ | |||
|
389 | for details. | |||
|
390 | ||||
|
391 | @doctest | |||
|
392 | ||||
|
393 | Compare the pasted in output in the ipython block with the output | |||
|
394 | generated at doc build time, and raise errors if they don't | |||
|
395 | match. Also, can be applied to the entire ``.. ipython`` block as a | |||
|
396 | directive option with ``:doctest:``. | |||
|
397 | ||||
|
398 | Configuration Options | |||
|
399 | ===================== | |||
|
400 | ||||
|
401 | ipython_savefig_dir | |||
|
402 | ||||
|
403 | The directory in which to save the figures. This is relative to the | |||
|
404 | Sphinx source directory. The default is `html_static_path`. | |||
|
405 | ||||
|
406 | ipython_rgxin | |||
|
407 | ||||
|
408 | The compiled regular expression to denote the start of IPython input | |||
|
409 | lines. The default is re.compile('In \[(\d+)\]:\s?(.*)\s*'). You | |||
|
410 | shouldn't need to change this. | |||
|
411 | ||||
|
412 | ipython_rgxout | |||
|
413 | ||||
|
414 | The compiled regular expression to denote the start of IPython output | |||
|
415 | lines. The default is re.compile('Out\[(\d+)\]:\s?(.*)\s*'). You | |||
|
416 | shouldn't need to change this. | |||
|
417 | ||||
|
418 | ||||
|
419 | ipython_promptin | |||
|
420 | ||||
|
421 | The string to represent the IPython input prompt in the generated ReST. | |||
|
422 | The default is 'In [%d]:'. This expects that the line numbers are used | |||
|
423 | in the prompt. | |||
|
424 | ||||
|
425 | ipython_promptout | |||
|
426 | ||||
|
427 | The string to represent the IPython prompt in the generated ReST. The | |||
|
428 | default is 'Out [%d]:'. This expects that the line numbers are used | |||
|
429 | in the prompt. | |||
|
430 | ||||
|
431 | ||||
|
432 | Automatically generated documentation | |||
|
433 | ===================================== | |||
|
434 | ||||
|
435 | .. automodule:: IPython.sphinxext.ipython_directive |
@@ -556,7 +556,7 b' class EmbeddedSphinxShell(object):' | |||||
556 |
|
556 | |||
557 | # output any exceptions raised during execution to stdout |
|
557 | # output any exceptions raised during execution to stdout | |
558 | # unless :okexcept: has been specified. |
|
558 | # unless :okexcept: has been specified. | |
559 | if not is_okexcept and "Traceback" in processed_output: |
|
559 | if not is_okexcept and (("Traceback" in processed_output) or ("SyntaxError" in processed_output)): | |
560 | s = "\nException in %s at block ending on line %s\n" % (filename, lineno) |
|
560 | s = "\nException in %s at block ending on line %s\n" % (filename, lineno) | |
561 | s += "Specify :okexcept: as an option in the ipython:: block to suppress this message\n" |
|
561 | s += "Specify :okexcept: as an option in the ipython:: block to suppress this message\n" | |
562 | sys.stdout.write('\n\n>>>' + ('-' * 73)) |
|
562 | sys.stdout.write('\n\n>>>' + ('-' * 73)) |
General Comments 0
You need to be logged in to leave comments.
Login now