使用 Sphinx 扩展自动生成 doctest 输出答案

【问题标题】：Auto generate doctest output with Sphinx extension使用 Sphinx 扩展自动生成 doctest 输出
【发布时间】：2012-03-21 17:06:34
【问题描述】：

我想我缺少关于 doctest 的 sphinx 扩展的一些内容。

文档中的典型例子是：

.. doctest::

   >>> print 1
   1

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

据我了解，可以运行：

$ make doctest

具有测试代码sn-ps的效果，并将真实输出与预期输出进行比较。例如，如果您有

.. doctest::

   >>> print 1
   3

doctest 会警告你它得到了1，而它期待3。

相反，我希望 sphinx 将真实输出单独插入到我的文档字符串或 .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]

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

【问题讨论】：

标签： python python-sphinx doctest

【解决方案1】：

我必须强烈（但友好地）反对你正在尝试做的事情。

您要问的是针对doctest module 的“测试部分”：

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

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

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

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

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

【讨论】：

谢谢！我意识到我误解了这个 sphinx 扩展的目的。我认为这更像是一种以更快的方式编写文档的方法，但现在我了解了 doctest 背后的整个想法。
OP 的要求非常合理，是大多数输入输出测试框架的共同特征（通常称为“接受”测试的输出）。请注意，OP 请求更新 source 文件（Python 程序中的文档字符串和 Sphinx 中的 doctest 块）的方法，而不是 Sphinx 生成的输出（HTML 或 LaTeX）。作为一种自动更新过时测试和示例的方法，这将非常有用。

【解决方案2】：

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

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

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

【讨论】：

【解决方案3】：

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

引用：

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

它是为几个用例设计的：

使用 doctest 并且不喜欢从 pytest 错误日志中手动复制生成的输出并将它们粘贴到他们的文档测试的记录输出。 pytest-accept 进行复制 & 为您粘贴。

通常认为编写测试有点烦人，并且更喜欢通过“运行代码并查看它是否有效”来进行开发的人。这库旨在让测试成为开发循环中令人愉悦的一部分。

【讨论】：