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

您还可以在多行输出上执行 doctesting。在 ipython 指令中使用随机数等非确定性输入时要小心，因为您的输入会通过一个实时解释器，因此如果您对随机输出进行 doctesting，您将收到一个错误。在这里，我们为确定性输出“播种”了随机数生成器，并且我们抑制了播种行，以便它不会显示在呈现的输出中

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

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

@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 形式插入输入和输出块，但自动增加行号。在内部，解释器将接收一个空字符串，因此它是一个保持行号一致的空操作。此外，还可以将 :verbatim: 作为指令选项应用于整个 ..ipython 块。

@savefig OUTFILE [IMAGE_OPTIONS]

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

@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]:’。这需要在提示符中使用行号。

在此页面上
在 GitHub 上编辑
显示源代码