Python doctests/sphinx：风格指南，如何使用这些和有一个可读的代码？

Question

我爱文档测试，它是唯一的测试framwork我使用的，因为它是如此之快写，因为狮身人面像用它做这么大的单证，几乎没有力气......

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

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

bla bla bla ... 

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

我的意思是，我把我的文档说明所有测试的模块的顶部，所以你必须愚蠢滚动查找实际的代码，这是相当丑陋（在我看来）。不过，我认为doctests应该仍然保留在模块中，因为您应该能够在阅读源代码时阅读它们。 所以，我的问题是：sphinx/doctests爱好者，你如何组织你的doctests，比如代码可读性不受影响？对于狮身人面像，文档测试有风格指南吗？对于狮身人面像的文档字符串，你使用google or sphinx style-guide还是别的？

Answer 1

我认为有两种doctest。

1. 你可以在函数的docstring中加入一些东西，但如果是这样的话，应该保持简洁。
2. 另一种选择是完整的文档/教程，我将其作为单独的文件来执行。

与普通文档不同，文档测试的美妙之处在于，即使它们不在同一个屏幕中，您仍然可以确信它们将与代码保持同步。阅读代码时，您想看到代码，也许只需要一些描述性文字。阅读教程时，您不希望看到代码只是示例。