：模式：sphinx.ext.doctest–文档中的测试片段¶

在文档中包含代码片段并演示执行它们的结果通常很有帮助。但是确保文档与代码保持最新是很重要的。

此扩展允许您以自然的方式测试文档中的此类代码片段。如果您按此处所示标记代码块，则“doctest”生成器将收集它们并将其作为doctest测试运行。

在每个文档中，可以将每个代码段分配给一个*组*。每组包括：

零个或多个*设置代码*块（例如导入要测试的模块）
一个或多个*测试*块

当使用“doctest”构建器构建文档时，将为每个文档收集组并逐个运行，首先执行安装代码块，然后按它们在文件中出现的顺序执行测试块。

有两种测试块：

*doctest style*块通过交错Python代码（包括解释器提示）和输出来模拟交互式会话。
*代码输出样式*块由一段普通的Python代码和一段可选的该代码的输出组成。

指令¶

下面的*group*参数解释如下：如果它为空，则块被分配给名为“default”的组。如果它是`*`，则块被分配给所有组（包括``default``组）。否则，它必须是以逗号分隔的组名列表。

.. testsetup:: [group]¶: 设置代码块。此代码不会显示在其他生成器的输出中，而是在它所属组的doctest之前执行。

.. testcleanup:: [group]¶: 清除代码块。此代码不会显示在其他生成器的输出中，而是在它所属组的doctest之后执行。

Added in version 1.1.

.. doctest:: [group]¶

doctest样式的代码块。您可以使用标准：mod:`doctest`标志来控制实际输出与输出结果的比较方式。默认标志集由：confval:`doctest_default_flags`配置变量指定。

该指令支持五个选项：

hide`，一个标志选项，在其他构建器中隐藏doctest块。默认情况下，它显示为高亮显示的doctest块。
options`，一个字符串选项，可用于提供一个逗号分隔的doctest标志列表，该列表适用于测试中的每个示例。（您仍然可以为每个示例提供显式标志，并带有doctest注释，但它们也会显示在其他构建器中。）
pyversion, a string option, can be used to specify the required Python version for the example to be tested. For instance, in the following case the example will be tested only for Python versions greater than 3.10:
```
.. doctest::
   :pyversion: > 3.10
```
支持以下操作数：
- ~=`：兼容释放子句
- =`：版本匹配子句
- =`：版本排除子句
- <=，>=`：包含有序比较子句
- <，>`：排他有序比较子句
- ==`：任意等式子句。
pyversion option is followed PEP-440: Version Specifiers.

Added in version 1.6.

在 1.7 版本发生变更: 支持的PEP-440操作数和符号
trim doctest flags``和``no trim doctest flags，一个标志选项，行末的doctest标志（看起来像``doctest:flag，```）和``1``标记分别删除（或不删除）。默认值为“trim doctest flags”。

注意，与标准doctest一样，您必须使用````在预期输出中发出空行信号。生成表示输出（HTML、LaTeX等）时，会删除“``”。

此外，还可以提供内联doctest选项，如doctest:：

>>> datetime.date.now()   # doctest: +SKIP
datetime.date(2008, 1, 1)

当测试运行时，它们将被尊重，但从表示输出中剥离。

.. testcode:: [group]¶

When the tests run, they are respected, but separated from the presentation output.

此指令支持三个选项：

hide`，一个标志选项，在其他生成器中隐藏代码块。默认情况下，它显示为高亮显示的代码块。
trim doctest flags``和``no trim doctest flags，一个标志选项，行末的doctest标志（看起来像``doctest:flag，```）和``1``标记分别删除（或不删除）。默认值为“trim doctest flags”。

备注

“testcode”块中的代码总是一次执行，不管它包含多少条语句。因此，将*不*为裸表达式生成输出–使用“print”。例子：：

.. testcode::

   1+1         # this will give no output!
   print(2+2)  # this will give output

.. testoutput::

   4

另外，请注意，由于doctest模块不支持在同一代码段中混合常规输出和异常消息，这也适用于testcode/testoutput。

.. testoutput:: [group]¶

最后一个的相应输出或异常消息：rst:方向：`testcode`块。

该指令支持四个选项：

hide`，一个标志选项，在其他构建器中隐藏输出块。默认情况下，它显示为不加亮显的文本块。
options`，一个字符串选项，可用于提供doctest标志（逗号分隔），就像在普通doctest块中一样。
trim doctest flags``和``no trim doctest flags，一个标志选项，行末的doctest标志（看起来像``doctest:flag，```）和``1``标记分别删除（或不删除）。默认值为“trim doctest flags”。

例如：

.. testcode::

   print('Output     text.')

.. testoutput::
   :hide:
   :options: -ELLIPSIS, +NORMALIZE_WHITESPACE

   Output text.

下面是指令用法的示例。测试通过：rst:方向：`doctest`和测试通过：rst:方向：`testcode`和：rst:方向：`testoutput`是等效的。:

The parrot module
=================

.. testsetup:: *

   import parrot

The parrot module is a module about parrots.

Doctest example:

.. doctest::

   >>> parrot.voom(3000)
   This parrot wouldn't voom if you put 3000 volts through it!

Test-Output example:

.. testcode::

   parrot.voom(3000)

This would output:

.. testoutput::

   This parrot wouldn't voom if you put 3000 volts through it!

有条件地跳过测试¶

skipif`，一个字符串选项，可用于有条件地跳过指令。这可能很有用，例如，根据环境（硬件、网络/VPN、可选依赖项或依赖项的不同版本）运行不同的测试集。所有doctest指令都支持“skipif”选项。以下是“skipif”在用于不同指令时的典型用例：

testsetup 和:rst:dir:testcleanup
- 有条件地跳过测试设置和/或清理
- 根据环境自定义安装/清理代码
doctest
- 有条件地跳过测试及其输出验证
testcode
- 有条件地跳过测试
- 每个自定义测试环境的代码
testoutput
- 有条件地跳过跳过测试的输出断言
- 根据环境的不同预期不同的输出

将Python`的值计算为’skif`表达式。如果结果是真值，则从测试运行中忽略该指令，就像它根本不存在于文件中一样。

可以使用：confval:`doctest_global_setup`配置选项将表达式分配给一个变量，然后可以使用该变量来代替该变量。

下面是一个例子，如果没有安装Pandas，它会跳过一些测试：

conf.py¶

extensions = ['sphinx.ext.doctest']
doctest_global_setup = '''
try:
    import pandas as pd
except ImportError:
    pd = None
'''

contents.rst¶

.. testsetup::
   :skipif: pd is None

   data = pd.Series([42])

.. doctest::
   :skipif: pd is None

   >>> data.iloc[0]
   42

.. testcode::
   :skipif: pd is None

   print(data.iloc[-1])

.. testoutput::
   :skipif: pd is None

   42

配置¶

doctest扩展使用以下配置值：

doctest_default_flags¶

默认情况下，这些选项处于启用状态：

ELLIPSIS，允许您将省略号放在与实际输出中的任何内容匹配的预期输出中；
IGNORE_EXCEPTION_DETAIL，导致忽略最左边冒号后面的所有内容以及异常名称中的任何模块信息；
``不要接受“1”的“TRUE”，拒绝在给定“1”的输出中的“TRUE”――接受此替换的默认行为是Python之前的2.2倍的产物。

Added in version 1.5.

doctest_show_successes¶

Defaults to True. Controls whether successes are reported.

For a project with many doctests, it may be useful to set this to False to only highlight failures.

Added in version 7.2.

doctest_path¶: 将添加到的目录列表：data:`搜索路径`当使用doctest构建器时。（确保它包含绝对路径。）

doctest_global_setup¶: 对于每个被测试的*文件和每个组，它被当作放在“testsetup”指令中的Python代码。您可以使用它来导入您的doctest中始终需要的模块。

Added in version 0.6.

doctest_global_cleanup¶: 对于每个测试的*文件和每个组，Python代码被视为放在“testcleanup”指令中。你可以用它来删除测试留下的任何临时文件。

Added in version 1.1.

doctest_test_doctest_blocks¶

For each test’s * file and each group, Python code is considered to be placed in the “testcleanup” instruction. You can use it to delete any temporary files left by the test.

其余的doctest块只是将doctest放入自己的一个段落中，如下所示：

Some documentation text.

>>> print(1)
1

Some more documentation text.

（请注意，没有特殊的“:：”用于引入doctest块；docutils从前导的“>>>”中识别它们。此外，不会使用额外的缩进，尽管不会造成伤害。）

如果将此值保留为默认值，则doctest构建器将对上面的代码段进行如下解释：

Some documentation text.

.. doctest::

   >>> print(1)
   1

Some more documentation text.

此功能使您可以轻松地测试：mod:`~sphinx.ext.autodoc`没有用特殊指令标记的扩展。

请注意，在reST doctest块中不能有空行。它们将被解释为一个街区结束，另一个街区开始。此外，删除```和``doctest:``选项仅适用于：rst:方向：`doctest`块，但是您可以设置：confval:`trim_doctest_flags`来在所有具有Python控制台内容的代码块中实现这一点。

Sphinx

On this page

Site navigation

：模式：sphinx.ext.doctest–文档中的测试片段¶

指令¶

有条件地跳过测试¶

配置¶