| 1 |
:mod:`!pydoc` --- Documentation generator and online help system |
| 2 |
================================================================ |
| 3 |
|
| 4 |
.. module:: pydoc |
| 5 |
:synopsis: Documentation generator and online help system. |
| 6 |
|
| 7 |
.. moduleauthor:: Ka-Ping Yee <[email protected]> |
| 8 |
.. sectionauthor:: Ka-Ping Yee <[email protected]> |
| 9 |
|
| 10 |
**Source code:** :source:`Lib/pydoc.py` |
| 11 |
|
| 12 |
.. index:: |
| 13 |
single: documentation; generation |
| 14 |
single: documentation; online |
| 15 |
single: help; online |
| 16 |
|
| 17 |
-------------- |
| 18 |
|
| 19 |
The :mod:`!pydoc` module automatically generates documentation from Python |
| 20 |
modules. The documentation can be presented as pages of text on the console, |
| 21 |
served to a web browser, or saved to HTML files. |
| 22 |
|
| 23 |
For modules, classes, functions and methods, the displayed documentation is |
| 24 |
derived from the docstring (i.e. the :attr:`~definition.__doc__` attribute) of the object, |
| 25 |
and recursively of its documentable members. If there is no docstring, |
| 26 |
:mod:`!pydoc` tries to obtain a description from the block of comment lines just |
| 27 |
above the definition of the class, function or method in the source file, or at |
| 28 |
the top of the module (see :func:`inspect.getcomments`). |
| 29 |
|
| 30 |
The built-in function :func:`help` invokes the online help system in the |
| 31 |
interactive interpreter, which uses :mod:`!pydoc` to generate its documentation |
| 32 |
as text on the console. The same text documentation can also be viewed from |
| 33 |
outside the Python interpreter by running :program:`pydoc` as a script at the |
| 34 |
operating system's command prompt. For example, running :: |
| 35 |
|
| 36 |
python -m pydoc sys |
| 37 |
|
| 38 |
at a shell prompt will display documentation on the :mod:`sys` module, in a |
| 39 |
style similar to the manual pages shown by the Unix :program:`man` command. The |
| 40 |
argument to :program:`pydoc` can be the name of a function, module, or package, |
| 41 |
or a dotted reference to a class, method, or function within a module or module |
| 42 |
in a package. If the argument to :program:`pydoc` looks like a path (that is, |
| 43 |
it contains the path separator for your operating system, such as a slash in |
| 44 |
Unix), and refers to an existing Python source file, then documentation is |
| 45 |
produced for that file. |
| 46 |
|
| 47 |
.. note:: |
| 48 |
|
| 49 |
In order to find objects and their documentation, :mod:`!pydoc` imports the |
| 50 |
module(s) to be documented. Therefore, any code on module level will be |
| 51 |
executed on that occasion. Use an ``if __name__ == '__main__':`` guard to |
| 52 |
only execute code when a file is invoked as a script and not just imported. |
| 53 |
|
| 54 |
When printing output to the console, :program:`pydoc` attempts to paginate the |
| 55 |
output for easier reading. If either the :envvar:`MANPAGER` or the |
| 56 |
:envvar:`PAGER` environment variable is set, :program:`pydoc` will use its |
| 57 |
value as a pagination program. When both are set, :envvar:`MANPAGER` is used. |
| 58 |
|
| 59 |
Specifying a ``-w`` flag before the argument will cause HTML documentation |
| 60 |
to be written out to a file in the current directory, instead of displaying text |
| 61 |
on the console. |
| 62 |
|
| 63 |
Specifying a ``-k`` flag before the argument will search the synopsis |
| 64 |
lines of all available modules for the keyword given as the argument, again in a |
| 65 |
manner similar to the Unix :program:`man` command. The synopsis line of a |
| 66 |
module is the first line of its documentation string. |
| 67 |
|
| 68 |
You can also use :program:`pydoc` to start an HTTP server on the local machine |
| 69 |
that will serve documentation to visiting web browsers. :program:`python -m pydoc -p 1234` |
| 70 |
will start a HTTP server on port 1234, allowing you to browse the |
| 71 |
documentation at ``http://localhost:1234/`` in your preferred web browser. |
| 72 |
Specifying ``0`` as the port number will select an arbitrary unused port. |
| 73 |
|
| 74 |
:program:`python -m pydoc -n <hostname>` will start the server listening at the given |
| 75 |
hostname. By default the hostname is 'localhost' but if you want the server to |
| 76 |
be reached from other machines, you may want to change the host name that the |
| 77 |
server responds to. During development this is especially useful if you want |
| 78 |
to run pydoc from within a container. |
| 79 |
|
| 80 |
:program:`python -m pydoc -b` will start the server and additionally open a web |
| 81 |
browser to a module index page. Each served page has a navigation bar at the |
| 82 |
top where you can *Get* help on an individual item, *Search* all modules with a |
| 83 |
keyword in their synopsis line, and go to the *Module index*, *Topics* and |
| 84 |
*Keywords* pages. |
| 85 |
|
| 86 |
When :program:`pydoc` generates documentation, it uses the current environment |
| 87 |
and path to locate modules. Thus, invoking :program:`pydoc spam` |
| 88 |
documents precisely the version of the module you would get if you started the |
| 89 |
Python interpreter and typed ``import spam``. |
| 90 |
|
| 91 |
Module docs for core modules are assumed to reside in |
| 92 |
``https://docs.python.org/X.Y/library/`` where ``X`` and ``Y`` are the |
| 93 |
major and minor version numbers of the Python interpreter. This can |
| 94 |
be overridden by setting the :envvar:`!PYTHONDOCS` environment variable |
| 95 |
to a different URL or to a local directory containing the Library |
| 96 |
Reference Manual pages. |
| 97 |
|
| 98 |
.. versionchanged:: 3.2 |
| 99 |
Added the ``-b`` option. |
| 100 |
|
| 101 |
.. versionchanged:: 3.3 |
| 102 |
The ``-g`` command line option was removed. |
| 103 |
|
| 104 |
.. versionchanged:: 3.4 |
| 105 |
:mod:`!pydoc` now uses :func:`inspect.signature` rather than |
| 106 |
:func:`inspect.getfullargspec` to extract signature information from |
| 107 |
callables. |
| 108 |
|
| 109 |
.. versionchanged:: 3.7 |
| 110 |
Added the ``-n`` option. |