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

2.1 版中的新Function。

源代码: Lib/pydoc.py


pydoc模块自动从 Python 模块生成文档。该文档可以在控制台上以文本页面的形式呈现,提供给 Web 浏览器或保存为 HTML 文件。

对于模块,类,函数和方法,显示的文档是从对象的文档字符串(即__doc__属性)派生的,并且是其文档成员的递归。如果没有文档字符串,则pydoc试图从 Comments 行的块中获取位于源文件中类,函数或方法的定义上方或模块顶部的描述(请参见inspect.getcomments())。

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

pydoc sys

在 shell 提示符下,将以类似于 Unix man 命令显示的手册页的样式在sys模块上显示文档。 pydoc 的参数可以是函数,模块或包的名称,也可以是对包中模块或模块内的类,方法或函数的点状引用.如果 pydoc **的参数看起来像一个路径(也就是说,它包含 os 的路径分隔符,例如 Unix 中的斜线),并且引用了现有的 Python 源文件,那么将为此生成文档文件。

Note

为了找到对象及其文档,pydoc导入要记录的模块。因此,此时将执行模块级别的任何代码。仅当将文件作为脚本调用而不仅仅是导入时,才使用if __name__ == '__main__':保护符来执行代码。

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

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

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

您还可以使用 pypydoc 在本地计算机上启动 HTTP 服务器,该 HTTP 服务器将为访问 Web 浏览器的文档提供服务。 pydoc -p 1234 将在端口 1234 上启动 HTTP 服务器,使您可以在首选的 Web 浏览器中的http://localhost:1234/浏览文档。 pydoc -g 将启动服务器,并另外启动一个小的基于Tkinter的图形界面,以帮助您搜索文档页面。

当 pydoc 生成文档时,它将使用当前环境和路径来查找模块。因此,调用 pydoc spam 会精确地记录您启动 Python 解释器并键入import spam时将获得的模块版本。

假定核心模块的模块文档位于https://docs.python.org/library/中。pass将 PYTHONDOCS环境变量设置为其他 URL 或包含“Library 参考手册”页面的本地目录,可以覆盖此设置。