从 Javadoc 迁移到 Python 文档

Question

所以我已经有点习惯于 Javadoc 风格的文档。 查看 Python 代码的各种示例，我发现，乍一看，文档似乎缺少很多信息。

好处：您很少看到不言而喻的文档。 文档字符串通常是一段或更少的英文标记，它集成在一起，而不是在单独的行中脱颖而出。

坏处：结合 Python 的鸭子类型，我发现许多函数不清楚它们期望的参数。 没有类型提示（鸭子提示？），而且通常情况下，最好有一些想法，即参数应该是类似列表、类似字符串、类似流的。

当然，Javadoc 是为低级语言设计的，没有 Python 强大的内省能力，这可能解释了不那么冗长的文档哲学。

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

Answer 1

reStructuredText格式是为了响应可以嵌入到文档字符串中的 Python 文档的需求而设计的，因此最好的方法是学习 reST 并使用该格式格式化文档字符串。 你可能会发现，就像我所做的那样，然后你继续格式化 reST 中的任何文档，但这是一个侧面:-)

为了专门记录您的 Python 代码， Sphinx系统是对 reST 格式的一组扩展，以及用于呈现文档的构建系统。 由于它旨在记录 Python 本身，包括标准库，因此Sphinx 允许对源代码进行结构良好的文档，当然包括您所要求的函数签名的细节。 它允许构建一个全面的文档套件，包括自动提取的和手写的，都使用相同的格式系统。

如果你只是想从你的源代码生成的文档，然后epydoc的将提取您的源代码API文档; 它也读取文本的 reST 格式。