IPython Sphinx 指令#

注意

这完全复制自旧的 IPython wiki，目前正在开发中。本开发指南的许多信息已过时。

ipython 指令是一个有状态的 ipython shell，用于嵌入 Sphinx 文档中。它识别标准的 ipython 提示符，并提取输入和输出行。这些提示符将从 1 开始重新编号。输入将送入嵌入式 ipython 解释器，并且该解释器的输出也将被插入。例如，像下面这样的代码块

.. code:: python3

   In [136]: x = 2

   In [137]: x**3
   Out[137]: 8

将呈现为

In [136]: x = 2

In [137]: x**3
Out[137]: 8

注意

本教程应与本文档的 Sphinx 源代码并排阅读，否则您将只能看到渲染的输出，而看不到生成它的代码。除了上述示例，本文档通常不会显示生成渲染输出的字面 ReST 代码。

先前会话的状态会被存储，并且标准错误会被捕获。在文档构建时，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

嵌入式解释器支持一些有限的标记。例如，您可以在 ipython 会话中添加注释，这些注释将按原样报告。还有一些方便的“伪装饰器”允许您对输出进行 doctest。输入会送入嵌入式 ipython 会话，ipython 会话的输出会插入到您的文档中。如果您的文档中的输出与 ipython 会话中的输出在 doctest 断言时不匹配，则会发生错误。

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

支持多行输入。

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',

您也可以对多行输出进行 doctest。但是在使用 ipython 指令中非确定性输入（例如随机数）时要小心，因为您的输入会通过一个实时解释器运行，因此如果您对随机输出进行 doctest，您将收到错误。这里我们“种子”随机数生成器以获得确定性输出，并且我们抑制种子行，使其不显示在渲染输出中

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]])

多行输入和输出的另一个演示

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

大多数“伪装饰器”都可以用作 ipython 模式的选项。例如，要设置 matplotlib pylab 但抑制输出，您可以这样做。使用 matplotlib use 指令时，它应该出现在任何 pylab 导入之前。这不会显示在渲染的文档中，但命令将在嵌入式解释器中执行，并且后续行号将递增以反映输入

.. code:: python3

   In [144]: from pylab import *

   In [145]: ion()

In [144]: from pylab import *

In [145]: ion()

同样，您可以设置 :doctest: 或 :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

您可以创建一个或多个 pyplot 图，并使用 @savefig 装饰器将其插入。

@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 [151]: ylabel('number')

In [152]: title('normal distribution')

@savefig hist_with_text.png width=4in
In [153]: grid(True)

您还可以将函数定义包含在源代码中。

In [3]: def square(x):
   ...:     """
   ...:     An overcomplicated square function as an example.
   ...:     """
   ...:     if x < 0:
   ...:         x = abs(x)
   ...:     y = x * x
   ...:     return y
   ...:

然后从后续部分调用它。

In [4]: square(3)
Out [4]: 9

In [5]: square(-2)
Out [5]: 4

编写纯 Python 代码#

纯 python 代码通过可选参数 python 支持。在这种纯 python 语法中，您不包含 python 解释器的输出。以下标记

.. code:: python

   foo = 'bar'
   print foo
   foo = 2
   foo**2

呈现为

foo = 'bar'
print foo
foo = 2
foo**2

我们甚至可以从 python 中绘图，使用 savefig 装饰器，并且用分号抑制输出

@savefig plot_simple_python.png width=4in
plot([1,2,3]);

同样，标准错误也被插入

foo = 'bar'
foo[)

注释被处理，状态被保留

# comments are handled
print foo

如果您看不到下一个代码块，则表示这些选项有效。

ioff()
ion()

处理多行输入。

line = 'Multi\
        line &\
        support &\
        works'
print line.split('&')

函数定义被正确解析

def square(x):
    """
    An overcomplicated square function as an example.
    """
    if x < 0:
        x = abs(x)
    y = x * x
    return y

并跨会话持久存在

print square(3)
print square(-2)

几乎所有您能用 ipython 代码做的事情，您都可以用一个简单的 python 脚本完成。显然，使用 doctest 选项没有意义。

伪装饰器#

以下是支持的装饰器，以及它们接受的任何可选参数。有些装饰器可以作为整个块的选项（例如 verbatim 和 suppress），有些只适用于它们正下方的行（例如 savefig）。

@suppress

执行 ipython 输入块，但从渲染输出中抑制输入和输出块。此外，可以作为指令选项 :suppress: 应用于整个 ..ipython 块。

@verbatim

按原样插入输入和输出块，但自动递增行号。在内部，解释器将被送入一个空字符串，因此它是一个保持行号一致的无操作。此外，可以作为指令选项 :verbatim: 应用于整个 ..ipython 块。

@savefig OUTFILE [IMAGE_OPTIONS]

将图形保存到静态目录并将其插入文档中，可能将其绑定到微型页面和/或放置代码/图形标签/引用以关联代码和图形。接受要传递给图像指令的参数（scale、width 等可以是 kwargs）；有关详细信息，请参阅图像选项。

@doctest

将 ipython 块中粘贴的输出与文档构建时生成的输出进行比较，如果不匹配则引发错误。此外，可以作为指令选项 :doctest: 应用于整个 ..ipython 块。

配置选项#

ipython_savefig_dir

保存图形的目录。这是相对于 Sphinx 源代码目录的。默认值为 html_static_path。

ipython_rgxin

编译后的正则表达式，用于表示 IPython 输入行的开始。默认值为 re.compile('In [(d+)]:s?(.*)s*')。您应该不需要更改此项。

ipython_rgxout

编译后的正则表达式，用于表示 IPython 输出行的开始。默认值为 re.compile('Out[(d+)]:s?(.*)s*')。您应该不需要更改此项。

ipython_promptin

在生成的 ReST 中表示 IPython 输入提示符的字符串。默认值为 'In [%d]:'。这期望在提示符中使用行号。

ipython_promptout

在生成的 ReST 中表示 IPython 提示符的字符串。默认值为 'Out [%d]:'。这期望在提示符中使用行号。

IPython Sphinx 指令#

编写纯 Python 代码#

伪装饰器#

配置选项#

此页面