2

我喜欢 doctests，它是我唯一使用的测试框架，因为它写起来非常快，而且因为与 sphinx 一起使用，它几乎不费吹灰之力就能制作出如此出色的文档......

然而，很多时候，我最终会做这样的事情：

"""
Descriptions
=============

bla bla bla ...

    >>> test
    1
bla bla bla + tests tests tests * 200 lines = poor readability of the actual code
"""

我的意思是我把我所有的测试和文档解释都放在了模块的顶部，所以你必须愚蠢地滚动才能找到实际的代码，这很丑陋（在我看来）。但是，我认为文档测试应该仍然保留在模块中，因为您应该能够在阅读源代码时阅读它们。所以我的问题来了：sphinx/doctests 爱好者，你如何组织你的 doctests，比如代码可读性不受影响？是否有针对 sphinx 的 doctests 样式指南？对于带有 sphinx 的文档字符串，您使用google 或 sphinx style-guide还是其他方式？

4

1 回答 1

3

我认为有两种doctest。

  1. 您可以在函数的文档字符串中添加一些内容，但如果是这样，请保持简短。
  2. 另一个选项是完整的文档/教程，我将其作为单独的文件进行。

与普通文档不同，doctesting 的美妙之处在于，即使它们不在同一个屏幕中，您也可以确保它们将与代码保持同步。阅读代码时，您想查看代码，可能带有一些描述性文字。阅读教程时，您不想只看到示例代码。

于 2010-05-25T07:34:20.727 回答