如何为Python包编写文档

Question

我知道怎么给函数、类和模块写文档，但我该怎么给包写文档呢？是把说明写在__init__.py里，还是别的地方呢？

Answer 1

写文档是个好主意，但前提是别去记录那些代码中显而易见的东西。

要明白，大多数看你代码的人都会懂Python，所以像下面这样的代码加注释就没什么意义：

a = 1     #this assigns 1 to a

但是，对于那些比较复杂的函数或类，写注释或文档就很有必要了。

一个简单的原则是：想象一下，下一个接手你代码的人是个拿着斧头的疯子，而且他们知道你住在哪里。

这样一来，你就会总是留下“有用”的注释和文档。

Answer 2

可以查看 PEP257

一个包的说明可以写在包目录下的 __ init __.py 文件的模块文档字符串里。

Answer 3

没错，就像给函数或类写注释一样，__init__.py 文件的第一行应该是一个注释字符串：

"""
This is the xyz package.
"""

现在如果你导入这个包，然后使用 help(package)，你就能看到你写的文档字符串。想了解更多，可以查看这里：http://www.python.org/dev/peps/pep-0257/