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

Question

我想我错过了关于doctest的sphinx扩展的一些内容.

文档中的典型示例是:

.. doctest::

   >>> print 1
   1

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

据我所知,可以运行:

$ make doctest

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

.. doctest::

   >>> print 1
   3

doctest会警告你1它正在期待它3.

相反,我希望sphinx在我的docstring或我的.rst文件中单独插入实际输出.例如,如果我们有类似的东西:

.. doctest::

    >>> print 1
    >>> print [2*x for x in range(3)]

我希望当我们运行make doctest一个选项时,它会将docstring更改为:

.. doctest::

   >>> print 1
   1
   >>> print [2*x for x in range(3)]
   [0,2,4]

我确信这是可能的,而且非常方便!

Answer 1

我必须强烈(但善意地)反对你要做的事情.

你问的是反对doctest模块的"测试部分" :

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

如果您编写输入和预期输出并让Python检查预期输出是否与实际输出匹配,则这些测试有一个原因.

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

注意:如果在函数内部没有逻辑(如果/ else,while循环,追加等等),则无需测试它们.并且测试不能重现测试逻辑,否则它们不再测试该功能.

我发现这个关于测试驱动开发的视频非常有趣,如果你想了解更多关于这个论点的话,也许你会感兴趣.

Answer 2

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

Doug Hellmann撰写了一篇有趣的文章,名为"使用Sphinx,Paver和Cog编写技术文档".它有一节描述了如何使用Cog工具自动运行代码示例并捕获输出以包含在Sphinx构建的文档中.

还有一个名为autorun的Sphinx扩展,它可以在特殊runblock指令中执行代码 并将输出附加到文档中.