Question

我想我错过了关于doctest的sphinx扩展的一些内容。

文档中的典型示例是：

.. doctest::

   >>> print 1
   1

有没有办法让sphinx自动生成输出（这里：1）？

据我了解，可以运行：

$ make doctest

具有测试代码片段的效果，并将实际输出与预期输出进行比较。例如，如果你有

.. doctest::

   >>> print 1
   3

doctest会警告你，1期待它3。

相反，我希望sphinx在我的docstring或我的.rst文件中单独插入实际输出。例如，如果我们有类似的东西：

.. doctest::

    >>> print 1
    >>> print [2*x for x in range(3)]

我希望当我们使用选项运行make doctest时，它会将文档字符串更改为：

.. doctest::

   >>> print 1
   1
   >>> print [2*x for x in range(3)]
   [0,2,4]

我确信这是可能的，而且非常方便！

Answer 1

我必须强烈（但善意地）建议反对你想要做的事情。

您要问的是doctest module：

的“测试部分”

doctest模块搜索看起来像交互式Python会话的文本片段，然后执行这些会话以验证它们是否完全如图所示。

这些测试有一个理由，如果你写入输入和预期的输出，让Python检查预期的输出是否与实际输出相匹配。

如果你让Python产生预期的输出，那么......它将不再是 expect （由用户/作者），因此doctests永远不会失败，因此这些测试将毫无用处。

注意：如果在函数内部没有逻辑（如果/ else，while循环，追加等等），则无需测试它们。并且测试不能重现测试逻辑，否则它们不再测试该函数。

我发现关于测试驱动开发的this video非常有趣，如果你想了解更多关于这个论点的话，也许你可能感兴趣。

Answer 2

以下是关于如何实现我怀疑您可能正在寻找的建议：

Doug Hellmann写了一篇名为Writing Technical Documentation with Sphinx, Paver, and Cog的有趣文章。它有a section描述如何使用Cog工具自动运行代码示例并捕获输出以包含在Sphinx构建的文档中。

还有一个contributed Sphinx extension called autorun可以执行特殊的代码 runblock指令并将输出附加到文档。

Answer 3

此功能作为 pytest-accept 的一部分以及 pytest 的扩展提供：https://github.com/max-sixty/pytest-accept

引用：

<块引用>

pytest-accept 是一个用于自动更新 doctest 的 pytest 插件输出。它运行 doctests，观察生成的输出，并写入将它们添加到 doctests 的文档输出中。

它是为几个用例而设计的：

使用 doctests 并且不喜欢从 pytest 错误日志手动复制生成的输出并将其粘贴到的人他们的文档测试的记录输出。 pytest-accept 进行复制 & 为您粘贴。
通常觉得编写测试有点烦人，并且更喜欢通过“运行代码并查看它是否有效”来进行开发的人。这库旨在让测试成为该开发循环中令人愉悦的一部分。