代码之家 › 专栏 › 技术社区 › sebpiq

pythondoctests/sphinx:样式指南,如何使用它们并拥有可读的代码?

doctest python-sphinx readability python

2

sebpiq · 技术社区 · 16 年前

我喜欢博士,这是我唯一使用的测试框架,因为它写起来很快,因为它与狮身人面像一起使用,几乎不费吹灰之力就能制作出如此伟大的文档。。。

然而,我经常会做这样的事情:

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

bla bla bla ...

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

我的意思是,我把所有的测试和文档解释放在模块的顶部,所以你必须愚蠢地滚动才能找到真正的代码,这是相当难看的(在我看来)。但是,我认为doctest应该仍然留在模块中,因为您应该能够在阅读源代码的同时阅读它们。所以我的问题来了:sphinx/doctests爱好者,如何组织你的doctests,比如代码的可读性不受影响?有医生的风格指南吗,斯芬克斯的?对于带有狮身人面像的docstring,您使用 google or sphinx style-guide

1 回复 | 直到 15 年前

1

3

Duncan 16 年前

我认为医生有两种。

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