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 所示的输出结果。


图 1 使用 pydoc 模块在控制台中查看文档

按下空格键,pydoc 将会使用第二屏来显示文档信息,如图 2 所示。


图 2 使用 pydoc 查看文档的第二屏信息

从图 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 所示的页面。

使用 pydoc 生成的 HTML 文档
图 3 使用 pydoc 生成的 HTML 文档

将图 3 所示的页面拉到下面,可以看到如图 4 所示的页面。

使用 pydoc 生成的文挡的第二屏信息
图 4 使用 pydoc 生成的文挡的第二屏信息

从图 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 模块列表

从图 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 所示的页面。


图 6 通过服务器查看 fkmodule 模块的信息

对比图 4 与图 6 所示的页面不难发现,它们显示的内容是一样的。因此,无论是生成 HTML 页面,还是直接启动 HTTP 服务器,都能看到相同的文档页面。

pydoc查找模块

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

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

例如,在 fkmodule.py 所在目录下运行如下命令:

python -m pydoc -k fk

可以看到如下输出信息:

fkmodule

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