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