pydoc

pydoc

pydoc是python自带模块，会根据 Python 模块来自动生成文档。生成的文档可在控制台中显示为文本页面，提供给 Web 浏览器访问或者保存为 HTML 文件。

使用pydoc可以很方便的查看类和方法结构，pydoc模块可以从python代码中获取docstring，然后生成帮助信息。

python的注释方法

1. 单行注释：使用#号进行注释
   ​#单行注释

2. 多行注释：使用三个双引号或单引号来注释多行内容
   ​'''
   ​ 单引号进行多行注释
   '''

   """
   双引号进行多行注释
   """

pydoc注释展示策略：

• functions和classes前面加#注释，
• function和class第一行内加三个单引号或三个双引号进行注释

如果有三个引号的注释方法，会优先使用三个点的注释，其次才展示#号的注释

注意：如果在方法或class定义后第一行使用#注释是拉取不到注释的

例子1：class前有#号注释，class内有多行注释，pydoc会优先展示三个点内的注释
例子2：方法内使用#号注释，pydoc不会显示注释内容（class同理）
例子3：方法或class没有多行注释，只在方法外有#号注释时，会展示定义前的#号内的内容
例子4：模块顶部的内容，优先展示多行注释中的内容

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 文件，使用浏览器打开该文件，可以看到页面。

不仅如此，pydoc 模块还可以查看当前操作系统中所有 Python 模块的 HTML 文档信息，有以下 2 种方式：

1. python -m pydoc -p 端口号
2. python -m pydoc -b
   其实，这 2 种方式是非常类似的，它们的区别是：前者使用指定的端口启动 HTTP 服务器，而后者将任意选择一个未被占用的端口来启动 HTTP 服务器。通过执行它们中的任意一个，都会打开浏览器并显示出一个包含所有 Pyhton 模块的 HTML 文档。

举个例子，执行如下命令：
python -m pydoc -p 8899
执行此命令，会看到如下输出信息：
Server ready at http://localhost:8899/
Server commands: [b]rowser, [q]uit
server>

显然，这里需要我们手动输入 b 或 q。其中，b 命令表示启动浏览器，而 q 命令表示退出。这里我们选择输入 b，此时浏览器会自动打开并自动访问 http://localhost:8899/， 将看到所示页面。

需要指明的一点是，pydoc 在显示所有 Python 模块时，会大致按照以下顺序进行显示：

• 显示 Python 内置的核心模块；
• 显示当前目录下的所有 Python 模块；
• 显示 PYTHONPATH 环境变量指定路径下包含的 Python 模块。

pydoc查找模块

pydoc 还提供了一个 -k 选项，该选项可以找到名称中包含执行字符串的所有模块。该选项的语法格式如下：
python -m pydoc -k 模块名

例如，在 demo.py 所在目录下运行如下命令：
python -m pydoc -k demo

可以看到如下输出信息：
......
demo

从上面的输出信息可以看到，pydoc 找到了所有包含“demo”的模块名，当然也包括我们自己创建的 demo.py。