pydoc — 文档生成器和在线帮助系统 — Python 文档

来自菜鸟教程
Python/docs/3.10/library/pydoc
跳转至:导航、​搜索

pydoc — 文档生成器和在线帮助系统

源代码: :source:`Lib/pydoc.py`



pydoc 模块自动从 Python 模块生成文档。 文档可以在控制台上显示为文本页面、提供给 Web 浏览器或保存为 HTML 文件。

对于模块、类、函数和方法,显示的文档来自文档字符串(即 对象的 __doc__ 属性),以及其可记录成员的递归。 如果没有文档字符串,pydoc 会尝试从源文件中类、函数或方法定义正上方或模块顶部的注释行块中获取描述(参见 [ X215X]inspect.getcomments())。

内置函数 help() 调用交互式解释器中的在线帮助系统,该系统使用 pydoc 在控制台上将其文档生成为文本。 通过在操作系统的命令提示符处将 pydoc 作为脚本运行,也可以从 Python 解释器外部查看相同的文本文档。 例如,运行

pydoc sys

在 shell 提示符下将显示有关 sys 模块的文档,其风格类似于 Unix man 命令显示的手册页。 pydoc 的参数可以是函数、模块或包的名称,也可以是对包中模块或模块内的类、方法或函数的点式引用。 如果 pydoc 的参数看起来像一个路径(也就是说,它包含操作系统的路径分隔符,例如 Unix 中的斜杠),并且引用现有的 Python 源文件,则生成文档对于那个文件。

笔记

为了查找对象及其文档,pydoc 导入要记录的模块。 因此,模块级别的任何代码都将在那个时候执行。 使用 if __name__ == '__main__': 守卫仅在文件作为脚本调用而不仅仅是导入时才执行代码。


将输出打印到控制台时,pydoc 尝试对输出进行分页以便于阅读。 如果设置了 PAGER 环境变量,pydoc 将使用其值作为分页程序。

在参数之前指定 -w 标志将导致 HTML 文档被写出到当前目录中的文件中,而不是在控制台上显示文本。

在参数前指定 -k 标志将在所有可用模块的概要行中搜索作为参数给出的关键字,再次以类似于 Unix man 命令的方式。 模块的概要行是其文档字符串的第一行。

您还可以使用 pydoc 在本地机器上启动一个 HTTP 服务器,该服务器将为访问的 Web 浏览器提供文档。 pydoc -p 1234 将在端口 1234 上启动 HTTP 服务器,允许您在首选 Web 浏览器中浏览 http://localhost:1234/ 中的文档。 指定 0 作为端口号将选择任意未使用的端口。

pydoc -n 将启动服务器侦听给定的主机名。 默认情况下,主机名是“localhost”,但如果您希望从其他机器访问服务器,您可能需要更改服务器响应的主机名。 在开发过程中,如果您想从容器内运行 pydoc,这尤其有用。

pydoc -b 将启动服务器并另外打开一个 web 浏览器到模块索引页面。 每个提供的页面顶部都有一个导航栏,您可以在其中 获取 单个项目的帮助,搜索 在概要行中包含关键字的所有模块,然后转到 模块索引主题关键字页面。

pydoc 生成文档时,它使用当前环境和路径来定位模块。 因此,如果您启动 Python 解释器并输入 import spam,调用 pydoc spam 可以准确记录您将获得的模块版本。

假设核心模块的模块文档位于 https://docs.python.org/X.Y/library/ 中,其中 XY 是 Python 解释器的主要和次要版本号。 这可以通过将 PYTHONDOCS 环境变量设置为不同的 URL 或包含库参考手册页面的本地目录来覆盖。

3.2 版更改: 增加了 -b 选项。


3.3 版更改: 删除了 -g 命令行选项。


3.4 版更改:pydoc 现在使用 inspect.signature() 而不是 inspect.getfullargspec() 从可调用文件中提取签名信息.


3.7 版更改: 增加了 -n 选项。