18.2 用pydoc编写文档

我们用库模块pydoc从Python代码中生成HTML文档。当我们在交互式Python环境中使用help()时，就是在使用这个模块。这个函数会生成不带标记的、基于文本模式的文档。

当我们用pydoc生成文档时，我们会以下面3种方式中的一种来使用它。

• 准备文本模式的文档文件，然后用命令行工具例如more或者less查看它们。
• 准备HTML文档并且保存在文件中以供之后的浏览使用。
• 运行一个HTTP服务器并且创建需要立刻浏览的HTML文件。

我们可以运行下面的命令行工具为某个模块准备基于文本的文档。

pydoc somemodule

我们也可以使用下面的代码。

python3.3 -m pydoc somemodule

任意一个命令都会基于Python代码创建文本文档。关于输出的显示，可以使用less（在Linux或Mac OS X上）或more（在Windows上）命令，这样可以将大量的输出在程序中分页显示。

在一般情况下，pydoc会假设我们提供了要导入的模块名称。这意味着该模块必须在Python的导入路径中。另外一种方式是，我们可以通过包含一个路径分隔符/（在Linux或Mac OS X上）或\（在Windows上）来指定一个带有.py扩展名的物理文件名。某些类似pydoc ./mymodule.py的命令可以获取导入路径之外的文件。

我们可以用-w选项来查看HTML文档。这个选项会将HTML文件写到本地目录中。

python3.3 -m pydoc -w somemodule

然后，我们可以在浏览器中打开somemodule.html来读取给定模块的文档。第3个选项是启动一个用于特殊目的的Web服务器来浏览包或模块的文档。除了简单地启动一个服务器之外，我们可以将启动服务器和加载默认浏览器的过程进行合并。下面是在8080端口启动一个服务器的简单方式。

python3.3 -m pydoc -p 8080

这行命令会启动一个HTTP服务器，这个服务器会查询当前目录中的代码。如果当前的目录是一个正确的包（也就是包含一个 init .py文件），那么这个服务器就会创建一个顶层模块索引。

一旦我们启动了一个服务器，就可以将浏览器定位到http://localhost:8080 来查看文档。我们也可以利用重写规则指向这个pydoc服务器上的一个本地Apache服务器，这样我们的团队就可以在Web服务器上共享这个文档。

我们也可以同时启动一个本地服务器和一个浏览器。

python3.3 -m pydoc –b

这行命令会定位一个未被使用的端口、启动一个服务器，然后启动指向这个服务器的默认浏览器。请注意，这里使用了python3.3命令，这在老版本的Python中无法工作。

自定义pydoc的输出不容易。各种样式和颜色都有效地硬编码在类定义中。修改和扩展pydoc，让它可以使用外部的CSS样式会是一项很有趣的工作。