1:mod:`pydoc` --- Documentation generator and online help system 2=============================================================== 3 4.. module:: pydoc 5 :synopsis: Documentation generator and online help system. 6.. moduleauthor:: Ka-Ping Yee <ping@lfw.org> 7.. sectionauthor:: Ka-Ping Yee <ping@lfw.org> 8 9 10.. versionadded:: 2.1 11 12.. index:: 13 single: documentation; generation 14 single: documentation; online 15 single: help; online 16 17**Source code:** :source:`Lib/pydoc.py` 18 19-------------- 20 21The :mod:`pydoc` module automatically generates documentation from Python 22modules. The documentation can be presented as pages of text on the console, 23served to a Web browser, or saved to HTML files. 24 25For modules, classes, functions and methods, the displayed documentation is 26derived from the docstring (i.e. the :attr:`__doc__` attribute) of the object, 27and recursively of its documentable members. If there is no docstring, 28:mod:`pydoc` tries to obtain a description from the block of comment lines just 29above the definition of the class, function or method in the source file, or at 30the top of the module (see :func:`inspect.getcomments`). 31 32The built-in function :func:`help` invokes the online help system in the 33interactive interpreter, which uses :mod:`pydoc` to generate its documentation 34as text on the console. The same text documentation can also be viewed from 35outside the Python interpreter by running :program:`pydoc` as a script at the 36operating system's command prompt. For example, running :: 37 38 pydoc sys 39 40at a shell prompt will display documentation on the :mod:`sys` module, in a 41style similar to the manual pages shown by the Unix :program:`man` command. The 42argument to :program:`pydoc` can be the name of a function, module, or package, 43or a dotted reference to a class, method, or function within a module or module 44in a package. If the argument to :program:`pydoc` looks like a path (that is, 45it contains the path separator for your operating system, such as a slash in 46Unix), and refers to an existing Python source file, then documentation is 47produced for that file. 48 49.. note:: 50 51 In order to find objects and their documentation, :mod:`pydoc` imports the 52 module(s) to be documented. Therefore, any code on module level will be 53 executed on that occasion. Use an ``if __name__ == '__main__':`` guard to 54 only execute code when a file is invoked as a script and not just imported. 55 56When printing output to the console, :program:`pydoc` attempts to paginate the 57output for easier reading. If the :envvar:`PAGER` environment variable is set, 58:program:`pydoc` will use its value as a pagination program. 59 60Specifying a ``-w`` flag before the argument will cause HTML documentation 61to be written out to a file in the current directory, instead of displaying text 62on the console. 63 64Specifying a ``-k`` flag before the argument will search the synopsis 65lines of all available modules for the keyword given as the argument, again in a 66manner similar to the Unix :program:`man` command. The synopsis line of a 67module is the first line of its documentation string. 68 69You can also use :program:`pydoc` to start an HTTP server on the local machine 70that will serve documentation to visiting Web browsers. :program:`pydoc -p 1234` 71will start a HTTP server on port 1234, allowing you to browse 72the documentation at ``http://localhost:1234/`` in your preferred Web browser. 73:program:`pydoc -g` will start the server and additionally bring up a 74small :mod:`Tkinter`\ -based graphical interface to help you search for 75documentation pages. 76 77When :program:`pydoc` generates documentation, it uses the current environment 78and path to locate modules. Thus, invoking :program:`pydoc spam` 79documents precisely the version of the module you would get if you started the 80Python interpreter and typed ``import spam``. 81 82Module docs for core modules are assumed to reside in 83https://docs.python.org/library/. This can be overridden by setting the 84:envvar:`PYTHONDOCS` environment variable to a different URL or to a local 85directory containing the Library Reference Manual pages. 86 87