|
@@
-2,12
+2,67
b''
|
|
2
|
"""
|
|
2
|
"""
|
|
3
|
Sphinx directive to support embedded IPython code.
|
|
3
|
Sphinx directive to support embedded IPython code.
|
|
4
|
|
|
4
|
|
|
|
|
|
5
|
IPython provides an extension for `Sphinx <http://www.sphinx-doc.org/>`_ to
|
|
|
|
|
6
|
highlight and run code.
|
|
|
|
|
7
|
|
|
5
|
This directive allows pasting of entire interactive IPython sessions, prompts
|
|
8
|
This directive allows pasting of entire interactive IPython sessions, prompts
|
|
6
|
and all, and their code will actually get re-executed at doc build time, with
|
|
9
|
and all, and their code will actually get re-executed at doc build time, with
|
|
7
|
all prompts renumbered sequentially. It also allows you to input code as a pure
|
|
10
|
all prompts renumbered sequentially. It also allows you to input code as a pure
|
|
8
|
python input by giving the argument python to the directive. The output looks
|
|
11
|
python input by giving the argument python to the directive. The output looks
|
|
9
|
like an interactive ipython section.
|
|
12
|
like an interactive ipython section.
|
|
10
|
|
|
13
|
|
|
|
|
|
14
|
Here is an example of how the IPython directive can
|
|
|
|
|
15
|
**run** python code, at build time.
|
|
|
|
|
16
|
|
|
|
|
|
17
|
.. ipython::
|
|
|
|
|
18
|
|
|
|
|
|
19
|
In [1]: 1+1
|
|
|
|
|
20
|
|
|
|
|
|
21
|
In [1]: import datetime
|
|
|
|
|
22
|
...: datetime.datetime.now()
|
|
|
|
|
23
|
|
|
|
|
|
24
|
It supports IPython construct that plain
|
|
|
|
|
25
|
Python does not understand (like magics):
|
|
|
|
|
26
|
|
|
|
|
|
27
|
.. ipython::
|
|
|
|
|
28
|
|
|
|
|
|
29
|
In [0]: import time
|
|
|
|
|
30
|
|
|
|
|
|
31
|
In [0]: %timeit time.sleep(0.05)
|
|
|
|
|
32
|
|
|
|
|
|
33
|
This will also support top-level async when using IPython 7.0+
|
|
|
|
|
34
|
|
|
|
|
|
35
|
.. ipython::
|
|
|
|
|
36
|
|
|
|
|
|
37
|
In [2]: import asyncio
|
|
|
|
|
38
|
...: print('before')
|
|
|
|
|
39
|
...: await asyncio.sleep(1)
|
|
|
|
|
40
|
...: print('after')
|
|
|
|
|
41
|
|
|
|
|
|
42
|
|
|
|
|
|
43
|
The namespace will persist across multiple code chucks, Let's define a variable:
|
|
|
|
|
44
|
|
|
|
|
|
45
|
.. ipython::
|
|
|
|
|
46
|
|
|
|
|
|
47
|
In [0]: who = "World"
|
|
|
|
|
48
|
|
|
|
|
|
49
|
And now say hello:
|
|
|
|
|
50
|
|
|
|
|
|
51
|
.. ipython::
|
|
|
|
|
52
|
|
|
|
|
|
53
|
In [0]: print('Hello,', who)
|
|
|
|
|
54
|
|
|
|
|
|
55
|
If the current section raises an exception, you can add the ``:okexcept:`` flag
|
|
|
|
|
56
|
to the current block, otherwise the build will fail.
|
|
|
|
|
57
|
|
|
|
|
|
58
|
.. ipython::
|
|
|
|
|
59
|
:okexcept:
|
|
|
|
|
60
|
|
|
|
|
|
61
|
In [1]: 1/0
|
|
|
|
|
62
|
|
|
|
|
|
63
|
IPython Sphinx directive module
|
|
|
|
|
64
|
===============================
|
|
|
|
|
65
|
|
|
11
|
To enable this directive, simply list it in your Sphinx ``conf.py`` file
|
|
66
|
To enable this directive, simply list it in your Sphinx ``conf.py`` file
|
|
12
|
(making sure the directory where you placed it is visible to sphinx, as is
|
|
67
|
(making sure the directory where you placed it is visible to sphinx, as is
|
|
13
|
needed for all Sphinx directives). For example, to enable syntax highlighting
|
|
68
|
needed for all Sphinx directives). For example, to enable syntax highlighting
|
|
@@
-27,19
+82,19
b' ipython_savefig_dir:'
|
|
27
|
Sphinx source directory. The default is `html_static_path`.
|
|
82
|
Sphinx source directory. The default is `html_static_path`.
|
|
28
|
ipython_rgxin:
|
|
83
|
ipython_rgxin:
|
|
29
|
The compiled regular expression to denote the start of IPython input
|
|
84
|
The compiled regular expression to denote the start of IPython input
|
|
30
|
lines. The default is re.compile('In \[(\d+)\]:\s?(.*)\s*'). You
|
|
85
|
lines. The default is ``re.compile('In \[(\d+)\]:\s?(.*)\s*')``. You
|
|
31
|
shouldn't need to change this.
|
|
86
|
shouldn't need to change this.
|
|
32
|
ipython_rgxout:
|
|
87
|
ipython_rgxout:
|
|
33
|
The compiled regular expression to denote the start of IPython output
|
|
88
|
The compiled regular expression to denote the start of IPython output
|
|
34
|
lines. The default is re.compile('Out\[(\d+)\]:\s?(.*)\s*'). You
|
|
89
|
lines. The default is ``re.compile('Out\[(\d+)\]:\s?(.*)\s*')``. You
|
|
35
|
shouldn't need to change this.
|
|
90
|
shouldn't need to change this.
|
|
36
|
ipython_promptin:
|
|
91
|
ipython_promptin:
|
|
37
|
The string to represent the IPython input prompt in the generated ReST.
|
|
92
|
The string to represent the IPython input prompt in the generated ReST.
|
|
38
|
The default is 'In [%d]:'. This expects that the line numbers are used
|
|
93
|
The default is ``'In [%d]:'``. This expects that the line numbers are used
|
|
39
|
in the prompt.
|
|
94
|
in the prompt.
|
|
40
|
ipython_promptout:
|
|
95
|
ipython_promptout:
|
|
41
|
The string to represent the IPython prompt in the generated ReST. The
|
|
96
|
The string to represent the IPython prompt in the generated ReST. The
|
|
42
|
default is 'Out [%d]:'. This expects that the line numbers are used
|
|
97
|
default is ``'Out [%d]:'``. This expects that the line numbers are used
|
|
43
|
in the prompt.
|
|
98
|
in the prompt.
|
|
44
|
ipython_mplbackend:
|
|
99
|
ipython_mplbackend:
|
|
45
|
The string which specifies if the embedded Sphinx shell should import
|
|
100
|
The string which specifies if the embedded Sphinx shell should import
|
|
@@
-54,7
+109,7
b' ipython_execlines:'
|
|
54
|
A list of strings to be exec'd in the embedded Sphinx shell. Typical
|
|
109
|
A list of strings to be exec'd in the embedded Sphinx shell. Typical
|
|
55
|
usage is to make certain packages always available. Set this to an empty
|
|
110
|
usage is to make certain packages always available. Set this to an empty
|
|
56
|
list if you wish to have no imports always available. If specified in
|
|
111
|
list if you wish to have no imports always available. If specified in
|
|
57
|
conf.py as `None`, then it has the effect of making no imports available.
|
|
112
|
``conf.py`` as `None`, then it has the effect of making no imports available.
|
|
58
|
If omitted from conf.py altogether, then the default value of
|
|
113
|
If omitted from conf.py altogether, then the default value of
|
|
59
|
['import numpy as np', 'import matplotlib.pyplot as plt'] is used.
|
|
114
|
['import numpy as np', 'import matplotlib.pyplot as plt'] is used.
|
|
60
|
ipython_holdcount
|
|
115
|
ipython_holdcount
|
|
@@
-105,21
+160,22
b' or :okwarning: options:'
|
|
105
|
In [2]: # raise warning.
|
|
160
|
In [2]: # raise warning.
|
|
106
|
|
|
161
|
|
|
107
|
To Do
|
|
162
|
To Do
|
|
108
|
-----
|
|
163
|
=====
|
|
109
|
|
|
164
|
|
|
110
|
- Turn the ad-hoc test() function into a real test suite.
|
|
165
|
- Turn the ad-hoc test() function into a real test suite.
|
|
111
|
- Break up ipython-specific functionality from matplotlib stuff into better
|
|
166
|
- Break up ipython-specific functionality from matplotlib stuff into better
|
|
112
|
separated code.
|
|
167
|
separated code.
|
|
113
|
|
|
168
|
|
|
114
|
Authors
|
|
|
|
|
115
|
-------
|
|
|
|
|
116
|
|
|
|
|
|
117
|
- John D Hunter: original author.
|
|
|
|
|
118
|
- Fernando Perez: refactoring, documentation, cleanups, port to 0.11.
|
|
|
|
|
119
|
- VáclavŠmilauer <eudoxos-AT-arcig.cz>: Prompt generalizations.
|
|
|
|
|
120
|
- Skipper Seabold, refactoring, cleanups, pure python addition
|
|
|
|
|
121
|
"""
|
|
169
|
"""
|
|
122
|
|
|
170
|
|
|
|
|
|
171
|
# Authors
|
|
|
|
|
172
|
# =======
|
|
|
|
|
173
|
#
|
|
|
|
|
174
|
# - John D Hunter: original author.
|
|
|
|
|
175
|
# - Fernando Perez: refactoring, documentation, cleanups, port to 0.11.
|
|
|
|
|
176
|
# - VáclavŠmilauer <eudoxos-AT-arcig.cz>: Prompt generalizations.
|
|
|
|
|
177
|
# - Skipper Seabold, refactoring, cleanups, pure python addition
|
|
|
|
|
178
|
|
|
123
|
#-----------------------------------------------------------------------------
|
|
179
|
#-----------------------------------------------------------------------------
|
|
124
|
# Imports
|
|
180
|
# Imports
|
|
125
|
#-----------------------------------------------------------------------------
|
|
181
|
#-----------------------------------------------------------------------------
|
|
@@
-145,6
+201,14
b' from traitlets.config import Config'
|
|
145
|
from IPython import InteractiveShell
|
|
201
|
from IPython import InteractiveShell
|
|
146
|
from IPython.core.profiledir import ProfileDir
|
|
202
|
from IPython.core.profiledir import ProfileDir
|
|
147
|
|
|
203
|
|
|
|
|
|
204
|
|
|
|
|
|
205
|
use_matpltolib = False
|
|
|
|
|
206
|
try:
|
|
|
|
|
207
|
import matplotlib
|
|
|
|
|
208
|
use_matpltolib = True
|
|
|
|
|
209
|
except Exception:
|
|
|
|
|
210
|
pass
|
|
|
|
|
211
|
|
|
148
|
#-----------------------------------------------------------------------------
|
|
212
|
#-----------------------------------------------------------------------------
|
|
149
|
# Globals
|
|
213
|
# Globals
|
|
150
|
#-----------------------------------------------------------------------------
|
|
214
|
#-----------------------------------------------------------------------------
|
|
@@
-325,13
+389,12
b' class EmbeddedSphinxShell(object):'
|
|
325
|
|
|
389
|
|
|
326
|
def process_input_line(self, line, store_history=True):
|
|
390
|
def process_input_line(self, line, store_history=True):
|
|
327
|
"""process the input, capturing stdout"""
|
|
391
|
"""process the input, capturing stdout"""
|
|
328
|
|
|
|
|
|
329
|
stdout = sys.stdout
|
|
392
|
stdout = sys.stdout
|
|
330
|
try:
|
|
393
|
try:
|
|
331
|
sys.stdout = self.cout
|
|
394
|
sys.stdout = self.cout
|
|
332
|
self.lines_waiting.append(line)
|
|
395
|
self.lines_waiting.append(line)
|
|
333
|
if self.IP.check_complete()[0] != 'incomplete':
|
|
396
|
source_raw = ''.join(self.lines_waiting)
|
|
334
|
source_raw = ''.join(self.lines_waiting)
|
|
397
|
if self.IP.check_complete(source_raw)[0] != 'incomplete':
|
|
335
|
self.lines_waiting = []
|
|
398
|
self.lines_waiting = []
|
|
336
|
self.IP.run_cell(source_raw, store_history=store_history)
|
|
399
|
self.IP.run_cell(source_raw, store_history=store_history)
|
|
337
|
finally:
|
|
400
|
finally:
|
|
@@
-501,6
+564,7
b' class EmbeddedSphinxShell(object):'
|
|
501
|
sys.stdout.write(s)
|
|
564
|
sys.stdout.write(s)
|
|
502
|
sys.stdout.write(processed_output)
|
|
565
|
sys.stdout.write(processed_output)
|
|
503
|
sys.stdout.write('<<<' + ('-' * 73) + '\n\n')
|
|
566
|
sys.stdout.write('<<<' + ('-' * 73) + '\n\n')
|
|
|
|
|
567
|
raise RuntimeError('Non Expected exception in `{}` line {}'.format(filename, lineno))
|
|
504
|
|
|
568
|
|
|
505
|
# output any warning raised during execution to stdout
|
|
569
|
# output any warning raised during execution to stdout
|
|
506
|
# unless :okwarning: has been specified.
|
|
570
|
# unless :okwarning: has been specified.
|
|
@@
-515,6
+579,7
b' class EmbeddedSphinxShell(object):'
|
|
515
|
w.filename, w.lineno, w.line)
|
|
579
|
w.filename, w.lineno, w.line)
|
|
516
|
sys.stdout.write(s)
|
|
580
|
sys.stdout.write(s)
|
|
517
|
sys.stdout.write('<<<' + ('-' * 73) + '\n')
|
|
581
|
sys.stdout.write('<<<' + ('-' * 73) + '\n')
|
|
|
|
|
582
|
raise RuntimeError('Non Expected warning in `{}` line {}'.format(filename, lineno))
|
|
518
|
|
|
583
|
|
|
519
|
self.cout.truncate(0)
|
|
584
|
self.cout.truncate(0)
|
|
520
|
|
|
585
|
|
|
@@
-866,7
+931,7
b' class IPythonDirective(Directive):'
|
|
866
|
# EmbeddedSphinxShell is created, its interactive shell member
|
|
931
|
# EmbeddedSphinxShell is created, its interactive shell member
|
|
867
|
# is the same for each instance.
|
|
932
|
# is the same for each instance.
|
|
868
|
|
|
933
|
|
|
869
|
if mplbackend and 'matplotlib.backends' not in sys.modules:
|
|
934
|
if mplbackend and 'matplotlib.backends' not in sys.modules and use_matpltolib:
|
|
870
|
import matplotlib
|
|
935
|
import matplotlib
|
|
871
|
matplotlib.use(mplbackend)
|
|
936
|
matplotlib.use(mplbackend)
|
|
872
|
|
|
937
|
|
|
@@
-985,7
+1050,9
b' def setup(app):'
|
|
985
|
|
|
1050
|
|
|
986
|
# If the user sets this config value to `None`, then EmbeddedSphinxShell's
|
|
1051
|
# If the user sets this config value to `None`, then EmbeddedSphinxShell's
|
|
987
|
# __init__ method will treat it as [].
|
|
1052
|
# __init__ method will treat it as [].
|
|
988
|
execlines = ['import numpy as np', 'import matplotlib.pyplot as plt']
|
|
1053
|
execlines = ['import numpy as np']
|
|
|
|
|
1054
|
if use_matpltolib:
|
|
|
|
|
1055
|
execlines.append('import matplotlib.pyplot as plt')
|
|
989
|
app.add_config_value('ipython_execlines', execlines, 'env')
|
|
1056
|
app.add_config_value('ipython_execlines', execlines, 'env')
|
|
990
|
|
|
1057
|
|
|
991
|
app.add_config_value('ipython_holdcount', True, 'env')
|
|
1058
|
app.add_config_value('ipython_holdcount', True, 'env')
|