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

源代码： Lib / pydoc.py

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

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

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

pydoc sys

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

注意

为了找到对象及其文档，pydoc导入要记录的模块。因此，模块级别上的任何代码都将在此时执行。使用if __ name __ == '__ main __'：当一个文件作为脚本调用，而不是只是导入。

当打印输出到控制台时，pydoc尝试对输出进行分页以便于阅读。If the PAGER environment variable is set, pydoc will use its value as a pagination program.

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

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

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

pydoc -b将启动服务器，并另外打开Web浏览器到模块索引页面。Each served page has a navigation bar at the top where you can Get help on an individual item, Search all modules with a keyword in their synopsis line, and go to the Module index, Topics and Keywords pages.

当pydoc生成文档时，它使用当前环境和路径来定位模块。因此，如果您启动Python解释器并输入import 垃圾邮件，则调用pydoc spam 。

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

在版本3.2中已更改：添加了-b选项。

在版本3.3中已更改：已删除-g命令行选项。

在版本3.4中更改： pydoc现在使用inspect.signature()而不是inspect.getfullargspec()