"pydoc" --- 文档生成器和在线帮助系统
************************************

**源代码:** Lib/pydoc.py

======================================================================

"pydoc" 模块会根据 Python 模块自动生成文档。生成的文档可在控制台中显示
为文本页面，提供给 Web 浏览器或者保存为 HTML 文件。

对于模块、类、函数和方法，显示的文档内容取自对象的文档字符串（即
"__doc__" 属性），并会递归地从其带有文档的成员中获取。如果没有文档字符
串，则 "pydoc" 会尝试从源文件中类、函数或方法的定义上方，或者模块最上
方的注释行代码块获取描述文本 (参见 "inspect.getcomments()")。

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

   python -m pydoc sys

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

备注:

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

当将输出打印到控制台时，**pydoc** 会尝试对输出进行分页以更容易阅读。如
果设置了 "MANPAGER" 或 "PAGER" 环境变量，**pydoc** 将使用其值作为分页
程序。当两者均被设置时，将使用 "MANPAGER".

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

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

你还可以使用 **pydoc** 在本机上启动一个 HTTP 服务器并向来访的 Web 浏览
器展示文档。 **python -m pydoc -p 1234** 将在 1234 端口上启动 HTTP 服
务器，允许在你所用的 Web 浏览器上通过 "http://localhost:1234/" 来浏览
文档。指定 "0" 作为端口号将任意选择一个未使用的端口。

**python -m pydoc -n <hostname>** 将启动在给定主机名上监听的服务器。默
认的主机名为 'localhost' 但是如果你希望能从其他机器上访问该服务器，你
可能会想要改变服务器所响应的主机名。 在开发阶段此特性会特别有用，如果
你想要在一个容器中运行 pydoc 的话。

**python -m pydoc -b** 将启动服务器并额外打开一个 Web 浏览器访问模块索
引页。 所发布的每个页面顶端都带有导航栏，你可以点击 *Get* 来获取特定条
目的帮助信息，点击 *Search* 在所有模块的摘要行中搜索某个关键词，或点击
*Module index*, *Topics* 和 *Keywords* 前往相应的页面。

当 **pydoc** 生成文档内容时，它会使用当前环境和路径来定位模块。因此，
唤起 **pydoc spam** 得到的文档版本会与你启动 Python 解释器并输入
"import 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()" 来从可调用对象中提取签名信息。

在 3.7 版本发生变更: 添加 "-n" 选项。
