所以我已经习惯了Javadoc风格的文档。通过各种Python代码示例，我发现，乍一看，文档似乎缺少大量信息。
好处：变化很少你看到不言而喻的文档。文档字符串通常是一段或更少的英文标记，它集成而不是分开排列。
糟糕：结合Python的鸭子打字，我发现很多函数都不清楚他们期望的参数。没有类型提示（duck-hinting？），而且经常会有一些想法，让参数应该像列表一样，类似于字符串，像流一样。
当然，Javadoc是为较低级别的语言设计的，没有Python的强大内省能力，这可能解释了较为冗长的文档哲学。
有关Python文档标准和最佳实践的任何建议吗？
答案 0 :(得分：9)
reStructuredText格式是为了响应对可以嵌入到文档字符串中的Python文档的需求而设计的，因此最好的方法是学习reST并使用该格式格式化文档字符串。你可能会发现，就像我一样，你继续在reST中格式化任何文档，但这是一个侧面点： - ）
为了专门记录您的Python代码，Sphinx系统是reST格式的一组扩展，以及用于呈现文档的构建系统。由于它设计用于记录Python本身，包括标准库， Sphinx允许非常结构良好的源代码文档，当然包括函数签名的具体细节。它允许构建一个全面的文档套件，包括自动提取和手写，都使用相同的格式化系统。
如果仅想要从源代码生成文档，那么 Epydoc将从源代码中提取API文档;它也会读取文本的reST格式。