cpython/Doc/library/pydoc.rst

101 lines
4.6 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:22 -03:00
:mod:`pydoc` --- Documentation generator and online help system
===============================================================
.. module:: pydoc
:synopsis: Documentation generator and online help system.
.. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
.. sectionauthor:: Ka-Ping Yee <ping@lfw.org>
.. index::
single: documentation; generation
single: documentation; online
single: help; online
2011-01-27 16:38:46 -04:00
**Source code:** :source:`Lib/pydoc.py`
--------------
2007-08-15 11:28:22 -03:00
The :mod:`pydoc` module automatically generates documentation from Python
modules. 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 is
derived from the docstring (i.e. the :attr:`__doc__` attribute) of the object,
and recursively of its documentable members. If there is no docstring,
:mod:`pydoc` tries to obtain a description from the block of comment lines just
above the definition of the class, function or method in the source file, or at
the top of the module (see :func:`inspect.getcomments`).
2007-08-15 11:28:22 -03:00
The built-in function :func:`help` invokes the online help system in the
interactive interpreter, which uses :mod:`pydoc` to generate its documentation
as text on the console. The same text documentation can also be viewed from
outside the Python interpreter by running :program:`pydoc` as a script at the
operating system's command prompt. For example, running ::
pydoc sys
at a shell prompt will display documentation on the :mod:`sys` module, in a
style similar to the manual pages shown by the Unix :program:`man` command. The
argument to :program:`pydoc` can be the name of a function, module, or package,
or a dotted reference to a class, method, or function within a module or module
in a package. If the argument to :program:`pydoc` looks like a path (that is,
it contains the path separator for your operating system, such as a slash in
Unix), and refers to an existing Python source file, then documentation is
produced for that file.
Merged revisions 67952,67957-67958,67960-67961,67963,67973,67978,67995,68030,68057,68061 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r67952 | georg.brandl | 2008-12-27 11:42:40 -0600 (Sat, 27 Dec 2008) | 2 lines #4752: actually use custom handler in example. ........ r67957 | georg.brandl | 2008-12-27 12:49:19 -0600 (Sat, 27 Dec 2008) | 2 lines #4754: improve winsound documentation. ........ r67958 | georg.brandl | 2008-12-27 13:02:59 -0600 (Sat, 27 Dec 2008) | 2 lines #4682: 'b' is actually unsigned char. ........ r67960 | georg.brandl | 2008-12-27 13:04:44 -0600 (Sat, 27 Dec 2008) | 2 lines #4695: fix backslashery. ........ r67961 | georg.brandl | 2008-12-27 13:06:04 -0600 (Sat, 27 Dec 2008) | 2 lines Use :samp: role. ........ r67963 | georg.brandl | 2008-12-27 13:11:15 -0600 (Sat, 27 Dec 2008) | 2 lines #4671: document that pydoc imports modules. ........ r67973 | alexandre.vassalotti | 2008-12-27 20:58:22 -0600 (Sat, 27 Dec 2008) | 2 lines Document Py_VaBuildValue. ........ r67978 | georg.brandl | 2008-12-28 05:58:49 -0600 (Sun, 28 Dec 2008) | 2 lines #4731: clarify message about missing module prerequisites. ........ r67995 | benjamin.peterson | 2008-12-28 15:16:07 -0600 (Sun, 28 Dec 2008) | 1 line #4763 PyErr_ExceptionMatches won't blow up with NULL arguments ........ r68030 | benjamin.peterson | 2008-12-29 15:38:14 -0600 (Mon, 29 Dec 2008) | 1 line fix French ........ r68057 | vinay.sajip | 2008-12-30 01:01:25 -0600 (Tue, 30 Dec 2008) | 1 line Minor documentation change relating to NullHandler. ........ r68061 | georg.brandl | 2008-12-30 04:15:49 -0600 (Tue, 30 Dec 2008) | 2 lines #4778: attributes can't be called. ........
2008-12-31 20:23:30 -04:00
.. note::
In order to find objects and their documentation, :mod:`pydoc` imports the
module(s) to be documented. Therefore, any code on module level will be
executed on that occasion. Use an ``if __name__ == '__main__':`` guard to
only execute code when a file is invoked as a script and not just imported.
When printing output to the console, :program:`pydoc` attempts to paginate the
output for easier reading. If the :envvar:`PAGER` environment variable is set,
:program:`pydoc` will use its value as a pagination program.
Specifying a ``-w`` flag before the argument will cause HTML documentation
2007-08-15 11:28:22 -03:00
to be written out to a file in the current directory, instead of displaying text
on the console.
Specifying a ``-k`` flag before the argument will search the synopsis
2007-08-15 11:28:22 -03:00
lines of all available modules for the keyword given as the argument, again in a
manner similar to the Unix :program:`man` command. The synopsis line of a
module is the first line of its documentation string.
You can also use :program:`pydoc` to start an HTTP server on the local machine
that will serve documentation to visiting Web browsers. :program:`pydoc -p 1234`
will start a HTTP server on port 1234, allowing you to browse the
documentation at ``http://localhost:1234/`` in your preferred Web browser.
Specifying ``0`` as the port number will select an arbitrary unused port.
:program:`pydoc -b` will start the server and additionally open a web
browser to a module index page. Each served page has a navigation bar at the
top where you can *Get* help on an individual item, *Search* all modules with a
keyword in their synopsis line, and go to the *Module index*, *Topics* and
*Keywords* pages.
2007-08-15 11:28:22 -03:00
When :program:`pydoc` generates documentation, it uses the current environment
and path to locate modules. Thus, invoking :program:`pydoc spam`
2007-08-15 11:28:22 -03:00
documents precisely the version of the module you would get if you started the
Python interpreter and typed ``import spam``.
Module docs for core modules are assumed to reside in
``https://docs.python.org/X.Y/library/`` where ``X`` and ``Y`` are the
major and minor version numbers of the Python interpreter. This can
be overridden by setting the :envvar:`PYTHONDOCS` environment variable
to a different URL or to a local directory containing the Library
Reference Manual pages.
2007-08-15 11:28:22 -03:00
.. versionchanged:: 3.2
Added the ``-b`` option.
.. versionchanged:: 3.3
The ``-g`` command line option was removed.
.. versionchanged:: 3.4
:mod:`pydoc` now uses :func:`inspect.signature` rather than
:func:`inspect.getfullargspec` to extract signature information from
callables.