Skip to main content

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

源代码: Lib/pydoc.py


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

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

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

pydoc sys

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

注解

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

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

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

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

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

pydoc -b 将启动服务器,并另外打开Web浏览器到模块索引页。每个页面都有一个导航栏,您可以在 Get 帮助单个项目,Search 所有模块与关键字在其概要行,并转到 模块索引TopicsKeywords 页面。

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() 从可调用项中提取签名信息。