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

Question

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

文档中的典型例子是:

.. doctest::

   >>> print 1
   1

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

据我了解，可以运行:

$ make doctest

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

.. 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]

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

Answer 1

我必须强烈(但善意地)反对你正在尝试做的事情。

你问的是针对 doctest module 的“测试部分” :

The doctest module searches for pieces of text that look like interactive Python sessions, and then executes those sessions to verify that they work exactly as shown.

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

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

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

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