Python pydoc模块详解：查看、生成帮助文档

前面己经介绍了为函数、类、方法等编写文档（只要在函数、类、方法定义后定义一个字符串即可）。前面也介绍了使用 help() 函数和 __doc__ 属性来查看函数、类、方法的文档，但这种方式总是在控制器中查看，有时候难免不太方便。

借助于 Python 自带的 pydoc 模块，可以非常方便地查看、生成帮助文档，该文档是 HTML 格式的，因此查看、使用起来非常方便。

这里先提供如下 Python 源文件（文件名为 fkmodule.py）：

MY_NAME = 'C语言中文网'

def say_hi(name):
    '''
    定义一个打招呼的函数
    返回对指定用户打招呼的字符串
    '''
    print("执行say_hi函数")
    return name + '您好！'
def print_rect(height, width):
    '''
    定义一个打印矩形的函数
    height - 代表矩形的高
    width - 代表矩形的宽
    '''
    print(('*' * width + '\n') * height)
class User:
    NATIONAL = 'China'
    '''
    定义一个代表用户的类
    该类包括name、age两个变量
    '''
    def __init__(self, name, age):
        '''
        name初始化该用户的name
        age初始化该用户的age
        '''
        self.name = name
        self.age = age
    def eat (food):
        '''
        定义用户吃东西的方法
        food - 代表用户正在吃的东西
        '''
        print('%s正在吃%s' % (self.name, food))

上面代码定义了一个 fkmodule.py 源文件，也就是定义了一个 fkmodule 模块，该模块为函数、类和方法都提供了文档说明。下面将会示范如何使用 pydoc 来查看、生成该模块的文档。

pydoc在控制台中查看文档

先看如何使用 pydoc 模块在控制台中查看 HTML 文档。使用 pydoc 模块在控制台中查看帮助文档的命令如下：

python -m pydoc 模块名

上面命令中的 -m 是 python 命令的一个选项，表示运行指定模块，此处表示运行 pydoc 模块。后面的“模块名”参数代表程序要查看的模块。

例如，在 fkmodule.py 文件所在目录下运行如下命令：

python -m pydoc fkmodule

上面命令表示使用 pydoc 查看 fkmodule 模块的命令。运行该命令，将看到如图 1 所示的输出结果。
按下空格键，pydoc 将会使用第二屏来显示文档信息，如图 2 所示。
从图 1 可以看出，使用 pydoc 在控制台中查看文档时，由于一屏无法显示所有的文档信息，因此同样需要以分屏的形式来显示，这样查看其实并不方便，与使用 help() 命令查看帮助信息的差别并不大。

当然，在使用 pydoc 查看帮助信息时，它会有自己的组织方式，它总是按如下顺序来显示模块中的全部内容：

• 模块的文档说明：就是＊.py 文件顶部的注释信息，这部分信息会被提取成模块的文档说明。
• CLASSES 部分：这部分会列出该模块所包含的全部类。
• FUNCTIONS 部分：这部分会列出该模块所包含的全部函数。
• DATA 部分：这部分会列出该模块所包含的全部成员变量。
• FILE 部分：这部分会显示该模块对应的源文件。

不管怎么样，直接在控制台中查看指定模块的帮助信息依然不太方便，下面将会使用 pydoc 来为指定模块生成 HTML 文档。

pydoc生成HTML文档

使用 pydoc 模块在控制台中查看帮助文档的命令如下：

python -m pydoc -w 模块名

上面命令主要就是为 pydoc 模块额外指定了 -w 选项，该选项代表 write，表明输出 HTML 文档。

例如，在 fkmodule.py 所在当前目录下运行如下命令：

python -m pydoc -w fkmodule

运行上面命令，可以看到系统生成“wrote fkmodule.html” 提示信息。接下来可以在该目录下发现额外生成了一个 fkmodule.html 文件，使用浏览器打开该文件，可以看到如图 3 所示的页面。
将图 3 所示的页面拉到下面，可以看到如图 4 所示的页面。
从图 3 和图 4 所示的页面来看，该 HTML 页面与在控制台中查看的文档信息基本相同，区别在于，由于这是一个 HTML 页面，因此用户可以拖动滑块来上、下滚动屏幕，以方便查看。

需要说明的是，pydoc 还可用于为指定目录生成 HTML 文档。例如，通过如下命令为指定目录下的所有模块生成 HTML 文档：

python3 -m pydoc -w 目录名

但上面命令有一个缺陷，那就是当该命令工具要展示目录下子文件的说明时，会去子目录下找对应的 .html 文件，如果文件不存在，就会显示 404 错误。

如果真的要查看指定目录下所有子目录中的文档信息，则建议启动本地服务器来查看。

启动本地服务器来查看文档信息

启动本地服务器来查看文档信息，可以使用如下两个命令：

python3 -m pydoc -p 端口号

在指定端口启动 HTTP 服务器，接下来用户可以通过浏览器来查看 Python 的所有模块的文档信息：

python3 -m pydoc -b

在任意一个未占用的端口启动HTTP服务器，接下来用户同样可以通过浏览器来查看 Python 的所有模块的文档信息。

例如，在文件当前所在目录下运行如下命令：

python -m pydoc -p 8899

该命令工具将会显示如下输出信息：

Server ready at http://localhost:8899/
Server commands: [b]rowser, [q]uit

上面的输出信息提示 HTTP 服务器正在 8899 端口提供服务器，用户可以输入 b 命令来启动浏览器（实际上用户可以自行启动浏览器），也可以输入 q 命令来停止服务器。

打开浏览器访问 http://localhost:8899/，将会看到如图 5 所示的页面。
从图 5 可以看出，该页面默认显示了当前 Python 的所有模块。其中：

• 第一部分显示 Python 内置的核心模块。
• 第二部分显示当前目录下的所有模块，此处显示的就是 fkmodule 模块。
• 第三部分显示 d:\python_module 目录下的所有模块，此时在该目录下并未包含任何模块。pydoc 之所以显示该目录，是因为本机配置了 PYTHONPATH 环境变量，其值为 .;d:\python_module，因此 pydoc 会自动显示该目录下的所有模块。换而言之，第三部分用于显示 PYTHONPATH 环境变量所指定路径下的模块。

如果读者将图 5 所示的页面向下拉，将会依次看到 Python 系统在 D:\Python\Python36\DLLs、D:\Python\Python36\lib、D:\Python\Python36\lib\site-packages 路径下的所有模块。

如果要查看指定模块，只要单击图 5 所示页面中的模块链接即可。例如，单击图 5 所示页面中的“fkmodule”模块链接，将会看到如图 6 所示的页面。
对比图 4 与图 6 所示的页面不难发现，它们显示的内容是一样的。因此，无论是生成 HTML 页面，还是直接启动 HTTP 服务器，都能看到相同的文档页面。

pydoc查找模块

此外，pydoc 还提供了一个 -k 选项，该选项用于查找模块。该选项的语法格式如下：

python -m pydoc -k 被搜索模块的部分内容

例如，在 fkmodule.py 所在目录下运行如下命令：

python -m pydoc -k fk

可以看到如下输出信息：

fkmodule

从上面的输出信息可以看到，pydoc 找到了包含“fk”的 fkmodule。