25.1. pydoc — 文档生成器和在线帮助系统 — Python 文档
25.1. pydoc — 文档生成器和在线帮助系统
2.1 版中的新功能。
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/ 中的文档。 pydoc -g 将启动服务器并额外显示一个基于 Tkinter 的小图形界面来帮助您搜索文档页面。
当 pydoc 生成文档时，它使用当前环境和路径来定位模块。 因此，如果您启动 Python 解释器并输入 import spam，调用 pydoc spam 可以准确记录您将获得的模块版本。
假设核心模块的模块文档位于 https://docs.python.org/library/ 中。 这可以通过将 PYTHONDOCS 环境变量设置为不同的 URL 或包含库参考手册页面的本地目录来覆盖。
