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

  • 内容
  • 评论
  • 相关

前面讲过,在创建函数、类以及类方法时,可以为它们添加说明性文档,即分别在函数体、类体以及类方法内部的首行添加具有说明性的字符串即可。例如:

#demo.py文件
def display(add):
    '''
    这是一个函数
    '''
    print(add)
   
class my_cla:
    '''
    这是一个类
    '''
    def say(self,add):
        '''
        这是一个类实例方法
        '''
        print(add)

如上所示,我们分别创建了 display() 函数和 my_cla 类,该类中还包含一个 say() 实例方法,并且我们为它们设置了说明性文档。

在此基础上,可以通过 help() 函数或者 __doc__ 属性来调用函数、类或者类方法的说明性文档。例如在上面程序的基础上,添加如下代码:

help(display)
help(my_cla)
help(my_cla.say)

执行程序,运行结果为:

Help on function display in module __main__:

display(add)
    这是一个函数

Help on class my_cla in module __main__:

class my_cla(builtins.object)
|  这是一个类

|  Methods defined here:

|  say(self, add)
|      这是一个类实例方法

|  ----------------------------------------------------------------------
|  Data descriptors defined here:

|  __dict__
|      dictionary for instance variables (if defined)

|  __weakref__
|      list of weak references to the object (if defined)

Help on function say in module __main__:

say(self, add)
    这是一个类实例方法

显然,我们调出了它们的说明性文档,但不得不说,该方法仅能通过编写调用代码在输出结果中查看,不是很方便。

实际上,Python 还提供了 pydoc 模块,通过该模块可以快速地生成程序的帮助文档。接下来就详细讲解 pydoc 模块的用法。

pydoc在控制台中查看文档

和 help() 及 __doc__ 不同,使用 pydoc 模块无需编写任何 python 代码,通过执行 python 命令即可查看程序中成员的说明性文档。

执行如下 Python 命令,即可在控制台查看指定模块的说明性文档,命令语法格式如下:

python -m pydoc 模块名

其中,-m 表示运行指定模块,这里表示要执行 pydoc 模块。注意在指定模块名时,除非其创建在 Python 解释器能自行找到的目录下,否则这里要明确模块所在的位置。

以 demo.py 文件为例,在控制台执行如下命令:

python -m pydoc demo

执行此命令,即可看到 demo.py 文件中 display() 函数、my_cla 类以及该类中 say() 实例方法的说明性文档。读者可自行执行该命令查看输出结果,这里不再给出执行结果。

值得一提的是,使用该命令在控制台输出执行模块的帮助信息时,可能一屏无法显示所有的信息,我们可以通过滚动鼠标滑轮或者按“空格”键来滑屏,查看后续的信息。

如果读者执行该命令,可以看到,对于模块中各个成员的说明性文档,该命令有自己的组织方法,即总是按如下顺序来显示:

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

pydoc生成HTML文档

除此之外,pydoc 还可以将指定模块的帮助信息提取出来,并自动组织成一个 HTML 文档。

使用 pydoc 模块生成 HTML 帮助文档的命令如下:

python -m pydoc -w 模块名

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

例如,在 demo.py 所在当前目录下运行如下命令:

python -m pydoc -w demo

运行上面命令,可以看到系统生成“wrote demo.html” 提示信息。接下来可以在该目录下发现额外生成了一个 demo.html 文件,使用浏览器打开该文件,可以看到如图 1 所示的页面。


图 1 使用 pydoc 生成的 HTML 文档

本文标题:Python pydoc模块详解:查看、生成帮助文档

本文地址:https://www.hosteonscn.com/4671.html

评论

0条评论

发表评论

邮箱地址不会被公开。 必填项已用*标注