一日一技：Python自带的文档生成模块

厨师：kingname

如果我们的注释写的足够规范，Python能够自动为我们生成非常好看的文档。

生成文档的模块叫做 pydoc，当我们安装完成Python以后，它就会被自动添加进环境变量里面。

为了演示 pydoc的使用方法，我们先创建两个.py文件，如下面两张图所示：

代码里面的注释已经解释了每个模块的功能，但是注释和代码混着毕竟看起来不方便，所以我们可以使用 pydoc来把注释生成文档。

在终端里面进入代码所在的文件夹，运行如下代码：

python3 -m pydoc SuperSpider

运行效果如下图所示：

文档和Linux的 man生成的文档别无二致。并且可以通过键盘上的 j或方向键下往下滚动屏幕，或者键盘上的 k或者方向键上往上滚动屏幕。

如果你觉得在命令行下面依然不方便，那么还可以自动生成一个HTTP服务。在当前文件夹下面执行命令：

python3 -m pydoc -p 8877

其中的 8877是端口号，你可以改成任何一个没有被占用的端口。

此时界面如下图所示：

在浏览器中打开：127.0.0.1:8877，可以看到如下页面：

其中箭头所指的地方就是你的模块。点进去就能看到代码文档了：

只要你按照PEP8的规范来写注释，那么这些注释都能通过pydoc直接转换为文档。