
``pydoc`` --- Documentation generator and online help system
************************************************************

**Source code:** Lib/pydoc.py

======================================================================

The ``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.

The built-in function ``help()`` invokes the online help system in the
interactive interpreter, which uses ``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
**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 ``sys`` module, in
a style similar to the manual pages shown by the Unix **man** command.
The argument to **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 **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.

Note: In order to find objects and their documentation, ``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.

Specifying a ``-w`` flag before the argument will cause HTML
documentation 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
lines of all available modules for the keyword given as the argument,
again in a manner similar to the Unix **man** command.  The synopsis
line of a module is the first line of its documentation string.

You can also use **pydoc** to start an HTTP server on the local
machine that will serve documentation to visiting Web browsers.
**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.

**pydoc -g** will start the server and additionally bring up a small
``tkinter``-based graphical interface to help you search for
documentation pages.  The ``-g`` option is deprecated, since the
server can now be controlled directly from HTTP clients.

**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.

When **pydoc** generates documentation, it uses the current
environment and path to locate modules.  Thus, invoking **pydoc spam**
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
``http://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 ``PYTHONDOCS`` environment variable to a
different URL or to a local directory containing the Library Reference
Manual pages.

Changed in version 3.2: Added the ``-b`` option, deprecated the ``-g``
option.
