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 程式碼#

偽裝飾器#

配置選項#

此頁面