Python doctests / sphinx：样式指南，如何使用它们并具有可读代码？

Question

我喜欢doctests，它是我使用的唯一测试框架，因为编写速度非常快，并且因为与sphinx一起使用它几乎不费力地制作出如此优秀的文档......

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

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

bla bla bla ...

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

我的意思是我将所有测试文档解释放在模块的顶部，因此您必须愚蠢地滚动才能找到实际的代码，这非常难看（在我看来）。但是，我认为doctests仍然应该保留在模块中，因为您应该能够在阅读源代码时阅读它们。 所以我的问题出现了：sphinx / doctests爱好者，你如何组织你的doctests，比如代码可读性不受影响？对于狮身人面像，是否有doctests的样式指南？对于使用sphinx的docstring，您使用google or sphinx style-guide还是其他什么？

Answer 1

我认为有两种doctest。

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

与普通文档不同，doctesting的优点在于，即使它们不在同一个屏幕中，您也可以确保它们与代码保持同步。在阅读您想要查看代码的代码时，可能会使用一些描述性文本。阅读教程时，您不希望仅仅看到示例中的代码。