显示代码示例¶

Python源代码或交互式会话的示例使用标准reST文本块表示。它们由前一段末尾的::开始，并由缩进分隔。

表示交互式会话需要包括提示符和输出以及Python代码。交互式会话不需要特殊标记。最后一行输入或输出提示后，不应有“未使用的”主提示符；不要写成下面这个例子：

>>> 1 + 1
2
>>>

语法突出显示使用Pygments完成，并以智能方式处理：

每个源文件都有一个“突出显示语言”。默认情况下是'python'，因为大多数文件必须突出显示Python片段，但文档范围的默认值可以使用highlight_language配置值设置。
在Python突出显示模式下，交互式会话被自动识别并突出显示。正常的Python代码只有当它是可解析的才突出显示（因此你可以使用Python作为默认值，但是散布的shell命令或其他代码块片段不会突出显示为Python）。
突出显示的语言可以使用突出显示指令进行更改，用法如下：
.. highlight:: language¶
例：
.. highlight:: c
使用此语言，直到遇到下一个highlight指令。
对于必须显示不同语言的代码段的文档，还有一个直接给出突出显示语言的code-block指令：
.. code-block:: language¶
像这样使用它：
.. code-block:: ruby Some Ruby code.
指令的别名sourcecode也适用。
突出显示语言的有效值有：
- none（无高亮显示）
- python（未设置highlight_language时为默认值）
- guess（让Pygments基于内容猜测词法分析器，仅适用于某些知名的语言）
- rest
- c
- ...以及Pygments支持的任何其他词法分析器别名。
如果使用所选语言突出显示失败（即Pygments发出一个“错误”标记），该块不会以任何方式突出显示。

行号¶

Pygments可以为代码块生成行号。对于自动突出显示的块（由::开头的），必须在highlight指令中使用linenothreshold选项打开行号：

.. highlight:: python
   :linenothreshold: 5

这将为长于五行的所有代码块生成行号。

对于代码块，可以使用linenos标志选项来打开单个块的行号：

.. code-block:: ruby
   :linenos:

   Some more Ruby code.

可以使用lineno-start选项选择第一行的行号。如果存在，linenos也会自动激活。

Some more Ruby code, with line numbering starting at 10.

此外，可以给予emphasize-lines选项以使Pygments强调特定行：

.. code-block:: python
   :emphasize-lines: 3,5

   def some_function():
       interesting = False
       print 'This line is highlighted.'
       print 'This one is not...'
       print '...but this one is.'

在版本1.1中已更改：添加emphasisize-lines。

在版本1.3中已更改：添加lineno-start。

Includes¶

.. literalinclude:: filename¶

可以通过将示例文本存储在仅包含纯文本的外部文件中来包括逐字显示的逐字显示。该文件可以使用literalinclude指令包含。[1]例如，要包括Python源文件example.py，请使用：

.. literalinclude:: example.py

文件名通常是相对于当前文件的路径。但是，如果它是绝对的（以/开始），它是相对于顶部源目录。

如果你给出具有所需制表符宽度的tab-width选项，则会展开输入中的制表符。

与code-block一样，指令支持linenos标志选项打开行号，lineno-start选项选择第一行的行号，强调特定行的emphasize-lines选项和用于选择与当前文件的标准语言不同的语言的language选项。带选项的示例：

.. literalinclude:: example.rb
   :language: ruby
   :emphasize-lines: 12,15-18
   :linenos:

假设被包含的文件以source_encoding编码。如果该文件具有不同的编码，你可以使用encoding选项指定：

.. literalinclude:: example.py
   :encoding: latin-1

该指令还支持仅包括文件的一部分。如果它是一个Python模块，你可以使用pyobject选项选择要包括的类、函数或方法：

.. literalinclude:: example.py
   :pyobject: Timer.start

这将只包括文件中Timer类中属于start()方法的代码行。

或者，你可以通过给出lines选项来精确指定要包括哪些行：

.. literalinclude:: example.py
   :lines: 1,3,5-10,20-

这包括行1、3，5到10行和20到最后一行。

控制文件的哪一部分的另一种方法是使用start-after和end-before选项（或只有其中一个）。如果start-after被指定为字符串选项，则只包括在包含该字符串的第一行之后的行。如果end-before被指定为字符串选项，则只包含位于包含该字符串的第一行之前的行。

当指定要显示的文件的特定部分时，准确地显示正在呈现的行是有用的。这可以使用lineno-match选项来完成。

你可以分别使用prepend和append选项，在所包含的代码前面添加和/或添加一行。这是有用的，例如用于突出显示不包括<?php/?>标记的代码。

如果你想显示代码的diff，你可以通过给出一个diff选项来指定旧文件：

.. literalinclude:: example.py
   :diff: example.py.orig

这以统一差异格式显示example.py和example.py.orig之间的差异。

版本0.4.3中的新功能： encoding选项。

版本0.6中的新功能： pyobject、lines、start-after和end-before选项，以及对绝对文件名的支持。

版本1.0中的新功能： prepend和append以及tab-width选项。

版本1.3中的新功能： diff选项。lineno-match选项。

Caption和名称¶

版本1.3中的新功能。

可以提供caption选项以在代码块之前显示该名称。可以为name选项提供可以使用ref引用的隐式目标名称。例如：

.. code-block:: python
   :caption: this.py
   :name: this-py

   print 'Explicit is better than implicit.'

literalinclude也支持caption和name选项。caption有一个额外的功能，如果你将值保留为空，则显示的文件名将完全是作为参数给出的文件名。

缩进¶

版本1.3中的新功能。

可以提供dedent选项来从代码块中剥离缩进字符。例如：

.. literalinclude:: example.rb
   :language: ruby
   :dedent: 4
   :lines: 10-15

code-block也支持dedent选项。

脚注

[1]	有一个标准的`.. include`指令，但如果没有找到文件，它会引发错误。这个命令只是发出警告。

目录

上一主题

下一主题

这一页

显示代码示例¶

行号¶

Includes¶

Caption和名称¶

缩进¶