Question

在交互模式下工作时，help函数是获取文档的好帮手。然而，想要更宏观的显示的话，PyDoc也提供GUI接口（简单并且可移植的Python/Tkinter脚本），可以将其报表通过HTML网页格式来呈现，可通过任何网页浏览器来查看。在这种模式下，PyDoc可以在本地运行，或者作为客户端/服务器模式中的远程服务器来运行。报表中会包含自动创建的超链接，让你能够点击应用程序中相关组件的文档。

要通过这种模式启动PyDoc，一般是先启动图14-1所示的搜索引擎GUI。你可以选择Windows Python的"Start"按钮中的"Module Docs"菜单来启动它，或者启动PythonTools目录下的pydocgui.pyw脚本（执行pydoc.py再带一个-g命令行参数也行）。输入你感兴趣的模块名称，然后按下回车键。Python会深入到模块的导入搜索路径（sys.path）从而寻找所请求的模块的索引内容。

图　15-1　Pydoc顶层搜索引擎GUI：输入你想找的模块名称，再按下回车键，选择该模块，然后按下"go to selected"（或者不使用模块名称，而是按下"open browser"来查看所有可用的模块）

一旦你找到对象，选取它，再点击"go to selected"。Python会在机器上打开网页浏览器，以HTML格式显示报表。图15-2显示的是内置的glob模块的PyDoc信息。

图　15-2　当你在图15-1GUI中找到一个模块并按下"go to selected"时，模块的文档会以HTML呈现，并显示在网页浏览器窗口中，就像这里所展示的

注意这个网页"Module"部分中的超链接：你可以点击这些超链接从而跳到相关（已导入）模块的PyDoc网页。就较大的网页而言，PyDoc也会产生超链接从而指向网页的不同部分。

就像help函数接口，GUI接口也能用在用户定义的模块上。图15-3显示的是针对我们的docstrings.py模块文件所产生的网页。

图　15-3　PyDoc可作为显示内置和用户定义的模块的文档页。这里的网页是用户定义模块的说明网页，显示了它从源代码中提取出的所有文档字符串（文档字符串）

PyDoc能以许多方式调整和启动，我们在这里不讨论。参考Python标准库手册中的内容来了解更多的细节。最后要提的是，PyDoc基本上是“免费”实现报表：如果你善于在文件中使用文档字符串，PyDoc会替你收集信息并排列其格式以便于显示。PyDoc只能帮助函数和模块这类东西，但是，提供一种简单的方式来读取这类工具的中级文档，其报表比单纯的属性列表更有用，但是，也比不上标准手册那么完整。

现在我来介绍一下PyDoc技巧。如果你在图15-1窗口中的顶端输入字段中让模块名称留空，然后按下"Open Browser"按钮，PyDoc会产生一个网页，其中包含了可能在计算机上导入的每个模块的超链接。这包括Python标准库模块、已安装的第三方扩展模块、位于导入搜索路径上的用户定义模块以及静态或动态连结的C程序模块。如果没有编写程序去查看模块的源代码，是很难获得这类信息的。

PyDoc也能把模块的HTML文档保存在文件中，以便在今后查看或打印。参考其文档来了解如何使用。此外，注意：如果对象是从标准输入读取数据的脚本，PyDoc可能无法很好的运行。Python会导入目标模块来查看其内容，然而以GUI模式执行时，可能和标准输入文字没有连结。不过，可以导入但无需立即输入所需要的模块，也可以在PyDoc中运行得很好。