17db96d56Sopenharmony_ci:mod:`pydoc` --- Documentation generator and online help system 27db96d56Sopenharmony_ci=============================================================== 37db96d56Sopenharmony_ci 47db96d56Sopenharmony_ci.. module:: pydoc 57db96d56Sopenharmony_ci :synopsis: Documentation generator and online help system. 67db96d56Sopenharmony_ci 77db96d56Sopenharmony_ci.. moduleauthor:: Ka-Ping Yee <ping@lfw.org> 87db96d56Sopenharmony_ci.. sectionauthor:: Ka-Ping Yee <ping@lfw.org> 97db96d56Sopenharmony_ci 107db96d56Sopenharmony_ci**Source code:** :source:`Lib/pydoc.py` 117db96d56Sopenharmony_ci 127db96d56Sopenharmony_ci.. index:: 137db96d56Sopenharmony_ci single: documentation; generation 147db96d56Sopenharmony_ci single: documentation; online 157db96d56Sopenharmony_ci single: help; online 167db96d56Sopenharmony_ci 177db96d56Sopenharmony_ci-------------- 187db96d56Sopenharmony_ci 197db96d56Sopenharmony_ciThe :mod:`pydoc` module automatically generates documentation from Python 207db96d56Sopenharmony_cimodules. The documentation can be presented as pages of text on the console, 217db96d56Sopenharmony_ciserved to a web browser, or saved to HTML files. 227db96d56Sopenharmony_ci 237db96d56Sopenharmony_ciFor modules, classes, functions and methods, the displayed documentation is 247db96d56Sopenharmony_ciderived from the docstring (i.e. the :attr:`__doc__` attribute) of the object, 257db96d56Sopenharmony_ciand recursively of its documentable members. If there is no docstring, 267db96d56Sopenharmony_ci:mod:`pydoc` tries to obtain a description from the block of comment lines just 277db96d56Sopenharmony_ciabove the definition of the class, function or method in the source file, or at 287db96d56Sopenharmony_cithe top of the module (see :func:`inspect.getcomments`). 297db96d56Sopenharmony_ci 307db96d56Sopenharmony_ciThe built-in function :func:`help` invokes the online help system in the 317db96d56Sopenharmony_ciinteractive interpreter, which uses :mod:`pydoc` to generate its documentation 327db96d56Sopenharmony_cias text on the console. The same text documentation can also be viewed from 337db96d56Sopenharmony_cioutside the Python interpreter by running :program:`pydoc` as a script at the 347db96d56Sopenharmony_cioperating system's command prompt. For example, running :: 357db96d56Sopenharmony_ci 367db96d56Sopenharmony_ci python -m pydoc sys 377db96d56Sopenharmony_ci 387db96d56Sopenharmony_ciat a shell prompt will display documentation on the :mod:`sys` module, in a 397db96d56Sopenharmony_cistyle similar to the manual pages shown by the Unix :program:`man` command. The 407db96d56Sopenharmony_ciargument to :program:`pydoc` can be the name of a function, module, or package, 417db96d56Sopenharmony_cior a dotted reference to a class, method, or function within a module or module 427db96d56Sopenharmony_ciin a package. If the argument to :program:`pydoc` looks like a path (that is, 437db96d56Sopenharmony_ciit contains the path separator for your operating system, such as a slash in 447db96d56Sopenharmony_ciUnix), and refers to an existing Python source file, then documentation is 457db96d56Sopenharmony_ciproduced for that file. 467db96d56Sopenharmony_ci 477db96d56Sopenharmony_ci.. note:: 487db96d56Sopenharmony_ci 497db96d56Sopenharmony_ci In order to find objects and their documentation, :mod:`pydoc` imports the 507db96d56Sopenharmony_ci module(s) to be documented. Therefore, any code on module level will be 517db96d56Sopenharmony_ci executed on that occasion. Use an ``if __name__ == '__main__':`` guard to 527db96d56Sopenharmony_ci only execute code when a file is invoked as a script and not just imported. 537db96d56Sopenharmony_ci 547db96d56Sopenharmony_ciWhen printing output to the console, :program:`pydoc` attempts to paginate the 557db96d56Sopenharmony_cioutput for easier reading. If the :envvar:`PAGER` environment variable is set, 567db96d56Sopenharmony_ci:program:`pydoc` will use its value as a pagination program. 577db96d56Sopenharmony_ci 587db96d56Sopenharmony_ciSpecifying a ``-w`` flag before the argument will cause HTML documentation 597db96d56Sopenharmony_cito be written out to a file in the current directory, instead of displaying text 607db96d56Sopenharmony_cion the console. 617db96d56Sopenharmony_ci 627db96d56Sopenharmony_ciSpecifying a ``-k`` flag before the argument will search the synopsis 637db96d56Sopenharmony_cilines of all available modules for the keyword given as the argument, again in a 647db96d56Sopenharmony_cimanner similar to the Unix :program:`man` command. The synopsis line of a 657db96d56Sopenharmony_cimodule is the first line of its documentation string. 667db96d56Sopenharmony_ci 677db96d56Sopenharmony_ciYou can also use :program:`pydoc` to start an HTTP server on the local machine 687db96d56Sopenharmony_cithat will serve documentation to visiting web browsers. :program:`python -m pydoc -p 1234` 697db96d56Sopenharmony_ciwill start a HTTP server on port 1234, allowing you to browse the 707db96d56Sopenharmony_cidocumentation at ``http://localhost:1234/`` in your preferred web browser. 717db96d56Sopenharmony_ciSpecifying ``0`` as the port number will select an arbitrary unused port. 727db96d56Sopenharmony_ci 737db96d56Sopenharmony_ci:program:`python -m pydoc -n <hostname>` will start the server listening at the given 747db96d56Sopenharmony_cihostname. By default the hostname is 'localhost' but if you want the server to 757db96d56Sopenharmony_cibe reached from other machines, you may want to change the host name that the 767db96d56Sopenharmony_ciserver responds to. During development this is especially useful if you want 777db96d56Sopenharmony_cito run pydoc from within a container. 787db96d56Sopenharmony_ci 797db96d56Sopenharmony_ci:program:`python -m pydoc -b` will start the server and additionally open a web 807db96d56Sopenharmony_cibrowser to a module index page. Each served page has a navigation bar at the 817db96d56Sopenharmony_citop where you can *Get* help on an individual item, *Search* all modules with a 827db96d56Sopenharmony_cikeyword in their synopsis line, and go to the *Module index*, *Topics* and 837db96d56Sopenharmony_ci*Keywords* pages. 847db96d56Sopenharmony_ci 857db96d56Sopenharmony_ciWhen :program:`pydoc` generates documentation, it uses the current environment 867db96d56Sopenharmony_ciand path to locate modules. Thus, invoking :program:`pydoc spam` 877db96d56Sopenharmony_cidocuments precisely the version of the module you would get if you started the 887db96d56Sopenharmony_ciPython interpreter and typed ``import spam``. 897db96d56Sopenharmony_ci 907db96d56Sopenharmony_ciModule docs for core modules are assumed to reside in 917db96d56Sopenharmony_ci``https://docs.python.org/X.Y/library/`` where ``X`` and ``Y`` are the 927db96d56Sopenharmony_cimajor and minor version numbers of the Python interpreter. This can 937db96d56Sopenharmony_cibe overridden by setting the :envvar:`PYTHONDOCS` environment variable 947db96d56Sopenharmony_cito a different URL or to a local directory containing the Library 957db96d56Sopenharmony_ciReference Manual pages. 967db96d56Sopenharmony_ci 977db96d56Sopenharmony_ci.. versionchanged:: 3.2 987db96d56Sopenharmony_ci Added the ``-b`` option. 997db96d56Sopenharmony_ci 1007db96d56Sopenharmony_ci.. versionchanged:: 3.3 1017db96d56Sopenharmony_ci The ``-g`` command line option was removed. 1027db96d56Sopenharmony_ci 1037db96d56Sopenharmony_ci.. versionchanged:: 3.4 1047db96d56Sopenharmony_ci :mod:`pydoc` now uses :func:`inspect.signature` rather than 1057db96d56Sopenharmony_ci :func:`inspect.getfullargspec` to extract signature information from 1067db96d56Sopenharmony_ci callables. 1077db96d56Sopenharmony_ci 1087db96d56Sopenharmony_ci.. versionchanged:: 3.7 1097db96d56Sopenharmony_ci Added the ``-n`` option. 110