pydoc — Documentation generator and online help system¶

Source code:Lib/pydoc.py

Thepydoc 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 (seeinspect.getcomments()).

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

python-mpydocsys

at a shell prompt will display documentation on thesys module, in astyle similar to the manual pages shown by the Unixman command. Theargument topydoc 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 topydoc 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.

When printing output to the console,pydoc attempts to paginate theoutput for easier reading. If either theMANPAGER or thePAGER environment variable is set,pydoc will use itsvalue as a pagination program. When both are set,MANPAGER is used.

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 Unixman command. The synopsis line of amodule is the first line of its documentation string.

You can also usepydoc to start an HTTP server on the local machinethat will serve documentation to visiting web browsers.python -m pydoc -p 1234will start a HTTP server on port 1234, allowing you to browse thedocumentation athttp://localhost:1234/ in your preferred web browser.Specifying0 as the port number will select an arbitrary unused port.

python -m 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.

python -m 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 canGet help on an individual item,Search all modules with akeyword in their synopsis line, and go to theModule index,Topics andKeywords pages.

Whenpydoc generates documentation, it uses the current environmentand path to locate modules. Thus, invokingpydoc spamdocuments precisely the version of the module you would get if you started thePython interpreter and typedimportspam.

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