pydoc — Documentation generator and online help system文档生成器和在线帮助系统

Source code: Lib/pydoc.py

The pydoc module automatically generates documentation from Python modules. pydoc模块自动从Python模块生成文档。The documentation can be presented as pages of text on the console, served to a web browser, or saved to HTML files.文档可以在控制台上以文本页的形式呈现，也可以提供给web浏览器，或者保存到HTML文件中。

For modules, classes, functions and methods, the displayed documentation is derived from the docstring (i.e. the __doc__ attribute) of the object, and recursively of its documentable members. 对于模块、类、函数和方法，显示的文档是从对象的docstring（即__doc__属性）及其可文档成员的递归派生而来的。If there is no docstring, pydoc tries to obtain a description from the block of comment lines just above the definition of the class, function or method in the source file, or at the top of the module (see inspect.getcomments()).如果没有docstring，pydoc会尝试从源文件中类、函数或方法定义上方或模块顶部的注释行块中获取描述（请参见inspect.getcomments()）。

The built-in function help() invokes the online help system in the interactive interpreter, which uses pydoc to generate its documentation as text on the console. 内置函数help()调用交互式解释器中的在线帮助系统，该系统使用pydoc在控制台上将文档生成为文本。The same text documentation can also be viewed from outside the Python interpreter by running pydoc as a script at the operating system’s command prompt. 通过在操作系统的命令提示符下将pydoc作为脚本运行，也可以从Python解释器外部查看相同的文本文档。For example, running例如，运行

pydoc sys

at a shell prompt will display documentation on the sys module, in a style similar to the manual pages shown by the Unix man command. 在shell提示符下，将显示sys模块上的文档，其样式类似于Unix man命令显示的手动页面。The argument to pydoc can be the name of a function, module, or package, or a dotted reference to a class, method, or function within a module or module in a package. pydoc的参数可以是函数、模块或包的名称，也可以是对包中模块或模块内的类、方法或函数的点式引用。If the argument to pydoc looks like a path (that is, it contains the path separator for your operating system, such as a slash in Unix), and refers to an existing Python source file, then documentation is produced for that file.如果pydoc的参数看起来像一个路径（也就是说，它包含操作系统的路径分隔符，例如Unix中的斜杠），并且引用了一个现有的Python源文件，那么就会为该文件生成文档。

Note

In order to find objects and their documentation, pydoc imports the module(s) to be documented. 为了找到对象及其文档，pydoc导入要文档化的模块。Therefore, any code on module level will be executed on that occasion. 因此，任何模块级的代码都将在这种情况下执行。Use an if __name__ == '__main__': guard to only execute code when a file is invoked as a script and not just imported.使用if __name__ == '__main__':护卫仅在将文件作为脚本调用而不仅仅是导入时执行代码。

When printing output to the console, pydoc attempts to paginate the output for easier reading. 当将输出打印到控制台时，pydoc会尝试对输出进行分页，以便于阅读。If the PAGER environment variable is set, pydoc will use its value as a pagination program.如果设置了PAGER环境变量，pydoc将使用其值作为分页程序。

Specifying a -w flag before the argument will cause HTML documentation to be written out to a file in the current directory, instead of displaying text on the console.在参数之前指定-w标志将导致HTML文档被写入当前目录中的文件，而不是在控制台上显示文本。

Specifying a -k flag before the argument will search the synopsis lines of all available modules for the keyword given as the argument, again in a manner similar to the Unix man command. 在参数之前指定-k标志将在所有可用模块的概要行中搜索作为参数的关键字，其方式与Unix man命令类似。The synopsis line of a module is the first line of its documentation string.模块的概要行是其文档字符串的第一行。

You can also use pydoc to start an HTTP server on the local machine that will serve documentation to visiting web browsers. 您还可以使用pydoc在本地机器上启动一个HTTP服务器，该服务器将向访问的web浏览器提供文档。pydoc -p 1234 will start a HTTP server on port 1234, allowing you to browse the documentation at http://localhost:1234/ in your preferred web browser. 将在端口1234上启动HTTP服务器，允许您在在您喜欢的web浏览器中浏览位于http://localhost:1234/的文档。Specifying 0 as the port number will select an arbitrary unused port.指定0作为端口号将选择任意未使用的端口。

pydoc -n <hostname> will start the server listening at the given hostname. 将在给定的主机名上启动服务器侦听。By default the hostname is ‘localhost’ but if you want the server to be reached from other machines, you may want to change the host name that the server responds to. 默认情况下，主机名为“localhost”，但如果希望从其他计算机访问服务器，则可能需要更改服务器响应的主机名。During development this is especially useful if you want to run pydoc from within a container.在开发过程中，如果您想在容器中运行pydoc，这一点尤其有用。

pydoc -b will start the server and additionally open a web browser to a module index page. 将启动服务器，并另外打开一个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.每个提供的页面顶部都有一个导航栏，您可以在其中Get单个项目的帮助，在其概要行中Search所有模块并使用关键字，然后转到模块索引、主题和关键字页面。

When pydoc generates documentation, it uses the current environment and path to locate modules. 当pydoc生成文档时，它使用当前环境和路径来定位模块。Thus, invoking pydoc spam documents precisely the version of the module you would get if you started the Python interpreter and typed import spam.因此，调用pydoc spam文档正是启动Python解释器并键入import spam时所获得的模块版本。

Module docs for core modules are assumed to reside in https://docs.python.org/X.Y/library/ where X and Y are the major and minor version numbers of the Python interpreter. 假设核心模块的模块文档位于https://docs.python.org/X.Y/library/其中X和Y是Python解释器的主要版本号和次要版本号。This can be overridden by setting the PYTHONDOCS environment variable to a different URL or to a local directory containing the Library Reference Manual pages.这可以通过将PYTHONDOCS环境变量设置为不同的URL或包含库参考手册页面的本地目录来覆盖。

Changed in version 3.2:版本3.2中更改： Added the -b option.添加了-b选项。

Changed in version 3.3:版本3.3中更改： The -g command line option was removed.已删除-g命令行选项。

Changed in version 3.4:版本3.4中更改： pydoc now uses inspect.signature() rather than inspect.getfullargspec() to extract signature information from callables.pydoc现在使用inspect.signature()而不是inspect.getfullargspec()从可调用文件中提取签名信息。

Changed in version 3.7:版本3.7中更改： Added the -n option.添加了-n选项。