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 的风格指南？在使用 sphinx 的文档字符串时，你们是用 谷歌或 sphinx 的风格指南，还是其他什么？

Answer 1

我觉得有两种类型的doctest。

1. 第一种是你可以把一些内容放在函数的文档字符串里，但如果这样做的话，最好保持简短和简单。
2. 第二种选择是写完整的文档或教程，我通常会把它们放在一个单独的文件里。

跟普通的文档不同，doctest的好处在于，即使它们不在同一个屏幕上，你也可以确保它们和代码保持一致。当你在看代码的时候，你希望看到的是代码，可能还会有一些简单的描述文字。而当你在看教程时，你不想看到代码，只想看到例子。