从Javadoc迁移到Python文档

Question

所以我已经习惯了Javadoc样式的文档。通过各种Python代码示例，我发现，乍一看，文档似乎缺少大量信息。

好：很少有你会看到不言自明的文档。文档字符串通常是一段或更少的英文标记，可以集成而不是单独列出。糟糕：与Python的duck-typing相结合，我发现很多函数都不清楚他们期望的参数。没有类型提示（duck-hinting？），并且经常有人认为该参数应该是列表式的，字符串式的，流式的。

当然，Javadoc是为较低级别的语言设计的，没有Python的高度自省能力，这可能解释了较为冗长的文档原理。

关于Python文档标准和最佳实践的任何建议？

Answer 1

reStructuredText格式的设计是为了回应可能嵌入到文档中的Python文档的需求，所以最好的办法是以的格式学习reST并格式化文档字符串。您可能会发现，像我一样，你之后再去格式休息只是任何文件，但这是一个面点:-)

对于专门记录您的Python代码，该Sphinx系统是一套reST格式的扩展，以及渲染文档的构建系统。由于它被设计用于记录Python本身，包括标准库，因此Sphinx允许源代码的结构良好的文档，当然包括函数签名的细节。它允许构建全面的文档套件，既可以自动提取也可以手写，全部使用相同的格式化系统。

如果你只希望从源代码生成的文档，然后Epydoc会从你的源代码提取API文档;它也会读取文本的reST格式。