Doc/library/pydoc.rst

   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 .. note::
  40
  41    In order to find objects and their documentation, :mod:`pydoc` imports the
  42    module(s) to be documented.  Therefore, any code on module level will be
  43    executed on that occasion.  Use an ``if __name__ == '__main__':`` guard to
  44    only execute code when a file is invoked as a script and not just imported.
  45
  46 Specifying a :option:`-w` flag before the argument will cause HTML documentation
  47 to be written out to a file in the current directory, instead of displaying text
  48 on the console.
  49
  50 Specifying a :option:`-k` flag before the argument will search the synopsis
  51 lines of all available modules for the keyword given as the argument, again in a
  52 manner similar to the Unix :program:`man` command.  The synopsis line of a
  53 module is the first line of its documentation string.
  54
  55 You can also use :program:`pydoc` to start an HTTP server on the local machine
  56 that will serve documentation to visiting Web browsers. :program:`pydoc`
  57 :option:`-p 1234` will start a HTTP server on port 1234, allowing you to browse
  58 the documentation at ``http://localhost:1234/`` in your preferred Web browser.
  59 :program:`pydoc` :option:`-g` will start the server and additionally bring up a
  60 small :mod:`Tkinter`\ -based graphical interface to help you search for
  61 documentation pages.
  62
  63 When :program:`pydoc` generates documentation, it uses the current environment
  64 and path to locate modules.  Thus, invoking :program:`pydoc` :option:`spam`
  65 documents precisely the version of the module you would get if you started the
  66 Python interpreter and typed ``import spam``.
  67
  68 Module docs for core modules are assumed to reside in
  69 http://docs.python.org/library/.  This can be overridden by setting the
  70 :envvar:`PYTHONDOCS` environment variable to a different URL or to a local
  71 directory containing the Library Reference Manual pages.
  72