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

Question

我想我遗漏了一些关于doctest的sphinx扩展。

文档中的典型示例是：

.. doctest::

   >>> print 1
   1

有没有办法让sphinx自动生成输出(这里是：1)？

据我所知，可以运行：

$ make doctest

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

.. doctest::

   >>> print 1
   3

doctest将警告您，它在预期3时获得了1。

相反，我希望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]

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

Answer 1

我必须强烈(但友善地)建议不要使用来做你想做的事情。

您所要求的是针对doctest module的“测试部分”

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

如果您编写输入和预期输出，并让Python检查预期输出是否与实际输出匹配，这些测试是有原因的。

如果让Python生成预期的输出，那么..它将不再是(用户/作者)所期望的，因此doctest永远不会失败，因此这些测试将是无用的。

注意:如果函数内部没有逻辑( If /else、while-loops、appends等)，则为。没有必要对它们进行测试。测试不能重复测试逻辑，否则他们就不再测试函数了。

我发现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是一个自动更新文档测试输出的pytest插件。它运行doctest，观察生成的输出，并将它们写入doctest的文档输出。

它是为一些用例而设计的：

• 那些使用doctest的人，他们不喜欢手动复制pytest错误日志中生成的输出，并将它们粘贴到他们的doctest的文档输出中。

-

• 会为你做复制和粘贴的工作。pytest accept的人通常觉得写测试有点烦人，他们喜欢通过“运行代码并看看它是否工作”来进行开发。这个库旨在使测试成为开发循环中令人愉快的一部分。