pydoc —- Documentation generator and online help system

Source code:Lib/pydoc.py

The pydoc module automatically generates documentation from Pythonmodules. The documentation can be presented as pages of text on the console,served to a Web browser, or saved to HTML files.

For modules, classes, functions and methods, the displayed documentation isderived from the docstring (i.e. the doc attribute) of the object,and recursively of its documentable members. If there is no docstring,pydoc tries to obtain a description from the block of comment lines justabove the definition of the class, function or method in the source file, or atthe top of the module (see inspect.getcomments()).

The built-in function help() invokes the online help system in theinteractive interpreter, which uses pydoc to generate its documentationas text on the console. The same text documentation can also be viewed fromoutside the Python interpreter by running pydoc as a script at theoperating system's command prompt. For example, running

pydoc sys

at a shell prompt will display documentation on the sys module, in astyle similar to the manual pages shown by the Unix man command. Theargument 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 modulein a package. If the argument to pydoc looks like a path (that is,it contains the path separator for your operating system, such as a slash inUnix), and refers to an existing Python source file, then documentation isproduced for that file.

注解

In order to find objects and their documentation, pydoc imports themodule(s) to be documented. Therefore, any code on module level will beexecuted on that occasion. Use an if name == 'main': guard toonly execute code when a file is invoked as a script and not just imported.

When printing output to the console, pydoc attempts to paginate theoutput for easier reading. If the PAGER environment variable is set,pydoc will use its value as a pagination program.

Specifying a -w flag before the argument will cause HTML documentationto be written out to a file in the current directory, instead of displaying texton the console.

Specifying a -k flag before the argument will search the synopsislines of all available modules for the keyword given as the argument, again in amanner similar to the Unix man command. The synopsis line of amodule is the first line of its documentation string.

You can also use pydoc to start an HTTP server on the local machinethat will serve documentation to visiting Web browsers. pydoc -p 1234will start a HTTP server on port 1234, allowing you to browse thedocumentation at http://localhost:1234/ in your preferred Web browser.Specifying 0 as the port number will select an arbitrary unused port.

pydoc -n <hostname> will start the server listening at the givenhostname. By default the hostname is 'localhost' but if you want the server tobe reached from other machines, you may want to change the host name that theserver responds to. During development this is especially useful if you wantto run pydoc from within a container.

pydoc -b will start the server and additionally open a webbrowser to a module index page. Each served page has a navigation bar at thetop where you can Get help on an individual item, Search all modules with akeyword in their synopsis line, and go to the Module index, Topics andKeywords pages.

When pydoc generates documentation, it uses the current environmentand path to locate modules. Thus, invoking pydoc spamdocuments precisely the version of the module you would get if you started thePython interpreter and typed import spam.

Module docs for core modules are assumed to reside inhttps://docs.python.org/X.Y/library/ where X and Y are themajor and minor version numbers of the Python interpreter. This canbe overridden by setting the PYTHONDOCS environment variableto a different URL or to a local directory containing the LibraryReference Manual pages.

在 3.2 版更改: Added the -b option.

在 3.3 版更改: The -g command line option was removed.

在 3.4 版更改: pydoc now uses inspect.signature() rather thaninspect.getfullargspec() to extract signature information fromcallables.

在 3.7 版更改: Added the -n option.