Python的函数和类文档最佳实践
我正在寻找function/类/模块文档的最佳做法，即在代码本身的意见。 理想情况下，我想要一个评论模板，这是人类可读和Python文档实用程序消耗。
我已阅读docstrings上的Python文档 。
我明白这个部分：
第一行应该始终是对象目的的简短摘要。 为了简洁起见，它不应该明确地声明对象的名字或者types，因为这些名字或者types可以通过其他方式获得（除非名字恰好是描述函数操作的动词）。 这行应该以大写字母开头，并以句号结尾。
如果文档string中有更多的行，则第二行应该是空白的，从总体上与描述的其余部分在视觉上是分开的。
这句话需要多一点解释：
以下几行应该是一个或多个描述对象的调用约定，副作用等的段落。
具体来说，我正在寻找好评的函数和类的例子。
你应该使用reStructuredText并检查出狮身人面像标记结构 。 所有时尚的年轻人都这样做。
你应该遵循文档string约定 。 即
它将函数或方法的效果规定为一个命令（“这样做”，“返回”）。
你应该避免不必要地重复自己，或者解释显而易见的东西。 什么不该做的例子：
def do_things(verbose=False): """Do some things. :param verbose: Be verbose (give additional messages). """ raise NotImplementedError 如果你想描述一些不明显的事情，那将是一个不同的故事。 例如，详细信息会导致在stdout或loggingstream上发生消息。 这不是特定于Python，而是遵循更多的手形波浪理想，例如自我logging代码和代码/文档DRY 。
尽量避免提及特定的types（抽象的或类似界面的types通常是可以的）。 提到协议通常更有用，从鸭子的angular度来看（即“可迭代”而不是set ，或“可变的有序序列”，而不是list ）。 我已经看到了一些非常重要的代码，WRT :rtype:和:type param:函数级文档，我发现这些代码与鸭子打字的心态不一致。
正如Emji所说，Django是一个很好的项目，可以遵循清晰，一致的风格指南。
例如，他们对Django风格指南的贡献甚至可以描述他们希望如何查看文档。 他们特别提到：
在文档中，使用“动作词”，如：
def foo(): """ Calculates something and returns the result. """ pass
下面是一个不能做的例子：
def foo(): """ Calculate something and return the result. """ pass
我认为最好的资源将是Documenting Python
引用：
本文档描述了我们文档的样式指南，为支持Python文档而引入的自定义reStructuredText标记，以及如何使用它以及Sphinx构build系统。
狮身人面像 ：官方的Python文档生成器
学习文档实践的最好方法可能是查看一个众所周知的项目的源代码。 像Djangoproject一样。
