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

问题描述

我想我漏掉了有关doctest的狮身人面像扩展的某些内容。

文档中的典型示例是：

.. doctest::

   >>> print 1
   1

有没有办法让Shinx自动生成输出(此处：1)？

据我所知，可以运行：

$ make doctest

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

.. doctest::

   >>> print 1
   3

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

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

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

---

解决方案

我必须强烈(但善意)建议您不要做您想做的事情。

您问的是doctest module的"测试部分"：

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

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

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

注意：如果函数内部没有逻辑(If/Else、While循环、追加等)没有必要对它们进行测试。并且测试不得重现测试逻辑，否则它们将不再测试函数。

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