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

2022-04-20 00:00:00 python python-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关于测试驱动开发非常有趣,如果您想更多地了解这个论点,也许您会感兴趣。

相关文章