从Javadoc迁移到Python文档

Question

我已经有点习惯使用Javadoc风格的文档了。最近看了一些Python代码的例子，发现这些文档乍一看似乎缺少很多信息。

好的方面是：很少能看到那些显而易见的文档。Python的文档字符串通常只有一段或更短，内容比较简洁，和代码融为一体，而不是单独占一行。

不好的方面是：结合Python的鸭子类型，我发现很多函数对它们期望的参数并不清楚。没有类型提示（可以叫做鸭子提示吗？），很多时候我们希望能知道参数应该是类似列表、字符串或流的东西。

当然，Javadoc是为一种较低级的语言设计的，而Python具有更强的自省能力，这可能是它文档风格不那么详细的原因。

有没有关于Python文档标准和最佳实践的建议呢？

Answer 1

reStructuredText（简称reST）格式是为了满足Python文档的需求而设计的，这种文档可以嵌入到代码的注释中。所以，最好的办法就是学习reST，并用这种格式来写你的代码注释。你可能会发现，像我一样，你会用reST格式来整理几乎所有的文档，不过这只是个小插曲:-)

如果你想专门为你的Python代码写文档，可以使用Sphinx系统。它是对reST格式的一些扩展，并且提供了一个构建系统来生成文档。因为Sphinx是为了记录Python本身而设计的，包括标准库，所以Sphinx可以很好地组织源代码的文档，当然也包括你提到的函数签名的具体信息。它允许你创建一个全面的文档套件，既可以自动提取，也可以手动编写，所有这些都使用同样的格式系统。

如果你只想从你的源代码生成文档，那么Epydoc可以从你的源代码中提取API文档; 它同样可以读取reST格式的文本。