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

2.1 新版功能.

源代码: Lib/pydoc.py

---

The pydoc module automatically generates documentation from Python modules. The documentation can be presented as pages of text on the console, served to a Web browser, or saved to HTML files.

对于模块、类、函数和方法，显示的文档内容取自文档字符串（即 __doc__ 属性），并会递归地从其带文档的成员中获取。 如果没有文档字符串，pydoc 会尝试从类、函数或方法定义上方，或是模块顶部的注释行段落获取 (参见 inspect.getcomments()).

内置函数 help() 会发起调用交互式解释器的在线帮助系统，该系统使用 pydoc 在终端上生成文本形式的文档内容。 同样的文本文档也可以在 Python 解释器以外通过在操作系统的命令提示符下以脚本方式运行 pydoc 来查看。 例如，运行

pydoc sys

在终端提示符下将通过 sys 模块显示文档内容，其样式类似于 Unix man 命令所显示的指南页面。 pydoc 的参数可以为函数、模块、包，或带点号的对模块中的类、方法或函数以及包中的模块的引用。 如果传给 pydoc 的参数像是一个路径（即包含所在操作系统的路径分隔符，例如 Unix 的正斜杠），并且其指向一个现有的 Python 源文件，则会为该文件生成文档内容。

注解

为了找到对象及其文档内容，pydoc 会导入文档所在的模块。 因此，任何模块层级的代码都将被执行。 请使用 if __name__ == '__main__': 语句来确保一个文件的特定代码仅在作为脚本被发起调用时执行而不是在被导入时执行。

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

在参数前指定 -w 旗标将把 HTML 文档写入到当前目录下的一个文件中，而不是在控制台中显示文本。

在参数前指定 -k 旗标将在全部可用模块的提要行中搜索参数所给定的关键字，具体方式同样类似于 Unix man 命令。 模块的提要行就是其文档字符串的第一行。

You can also use pydoc to start an HTTP server on the local machine that will serve documentation to visiting Web browsers. pydoc -p 1234 will start a HTTP server on port 1234, allowing you to browse the documentation at http://localhost:1234/ in your preferred Web browser. pydoc -g will start the server and additionally bring up a small Tkinter-based graphical interface to help you search for documentation pages.

当 pydoc 生成文档内容时，它会使用当前环境和路径来定位模块。 因此，发起调用 pydoc spam 得到的文档版本会与你启动 Python 解释器并输入 import spam 时得到的模块版本完全相同。

Module docs for core modules are assumed to reside in https://docs.python.org/library/. This can be overridden by setting the PYTHONDOCS environment variable to a different URL or to a local directory containing the Library Reference Manual pages.