1 

     2 :mod:`pydoc` --- Documentation generator and online help system

     3 ===============================================================

     4 

     5 .. module:: pydoc

     6    :synopsis: Documentation generator and online help system.

     7 .. moduleauthor:: Ka-Ping Yee <ping@lfw.org>

     8 .. sectionauthor:: Ka-Ping Yee <ping@lfw.org>

     9 

    10 

    11 .. versionadded:: 2.1

    12 

    13 .. index::

    14    single: documentation; generation

    15    single: documentation; online

    16    single: help; online

    17 

    18 The :mod:`pydoc` module automatically generates documentation from Python

    19 modules.  The documentation can be presented as pages of text on the console,

    20 served to a Web browser, or saved to HTML files.

    21 

    22 The built-in function :func:`help` invokes the online help system in the

    23 interactive interpreter, which uses :mod:`pydoc` to generate its documentation

    24 as text on the console.  The same text documentation can also be viewed from

    25 outside the Python interpreter by running :program:`pydoc` as a script at the

    26 operating system's command prompt. For example, running ::

    27 

    28    pydoc sys

    29 

    30 at a shell prompt will display documentation on the :mod:`sys` module, in a

    31 style similar to the manual pages shown by the Unix :program:`man` command.  The

    32 argument to :program:`pydoc` can be the name of a function, module, or package,

    33 or a dotted reference to a class, method, or function within a module or module

    34 in a package.  If the argument to :program:`pydoc` looks like a path (that is,

    35 it contains the path separator for your operating system, such as a slash in

    36 Unix), and refers to an existing Python source file, then documentation is

    37 produced for that file.

    38 

    39 Specifying a :option:`-w` flag before the argument will cause HTML documentation

    40 to be written out to a file in the current directory, instead of displaying text

    41 on the console.

    42 

    43 Specifying a :option:`-k` flag before the argument will search the synopsis

    44 lines of all available modules for the keyword given as the argument, again in a

    45 manner similar to the Unix :program:`man` command.  The synopsis line of a

    46 module is the first line of its documentation string.

    47 

    48 You can also use :program:`pydoc` to start an HTTP server on the local machine

    49 that will serve documentation to visiting Web browsers. :program:`pydoc`

    50 :option:`-p 1234` will start a HTTP server on port 1234, allowing you to browse

    51 the documentation at ``http://localhost:1234/`` in your preferred Web browser.

    52 :program:`pydoc` :option:`-g` will start the server and additionally bring up a

    53 small :mod:`Tkinter`\ -based graphical interface to help you search for

    54 documentation pages.

    55 

    56 When :program:`pydoc` generates documentation, it uses the current environment

    57 and path to locate modules.  Thus, invoking :program:`pydoc` :option:`spam`

    58 documents precisely the version of the module you would get if you started the

    59 Python interpreter and typed ``import spam``.

    60 

    61 Module docs for core modules are assumed to reside in

    62 http://docs.python.org/library/.  This can be overridden by setting the

    63 :envvar:`PYTHONDOCS` environment variable to a different URL or to a local

    64 directory containing the Library Reference Manual pages.

    65