Doc/lib/libpydoc.tex

   1 \section{\module{pydoc} ---
   2          Documentation generator and online help system}
   3
   4 \declaremodule{standard}{pydoc}
   5 \modulesynopsis{Documentation generator and online help system.}
   6 \moduleauthor{Ka-Ping Yee}{ping@lfw.org}
   7 \sectionauthor{Ka-Ping Yee}{ping@lfw.org}
   8
   9 \versionadded{2.1}
  10 \index{documentation!generation}
  11 \index{documentation!online}
  12 \index{help!online}
  13
  14 The \module{pydoc} module automatically generates documentation from
  15 Python modules.  The documentation can be presented as pages of text
  16 on the console, served to a Web browser, or saved to HTML files.
  17
  18 The built-in function \function{help()} invokes the online help system
  19 in the interactive interpreter, which uses \module{pydoc} to generate
  20 its documentation as text on the console.  The same text documentation
  21 can also be viewed from outside the Python interpreter by running
  22 \program{pydoc} as a script at the operating system's command prompt.
  23 For example, running
  24
  25 \begin{verbatim}
  26 pydoc sys
  27 \end{verbatim}
  28
  29 at a shell prompt will display documentation on the \refmodule{sys}
  30 module, in a style similar to the manual pages shown by the \UNIX{}
  31 \program{man} command.  The argument to \program{pydoc} can be the name
  32 of a function, module, or package, or a dotted reference to a class,
  33 method, or function within a module or module in a package.  If the
  34 argument to \program{pydoc} looks like a path (that is, it contains the
  35 path separator for your operating system, such as a slash in \UNIX),
  36 and refers to an existing Python source file, then documentation is
  37 produced for that file.
  38
  39 Specifying a \programopt{-w} flag before the argument will cause HTML
  40 documentation to be written out to a file in the current directory,
  41 instead of displaying text on the console.
  42
  43 Specifying a \programopt{-k} flag before the argument will search the
  44 synopsis lines of all available modules for the keyword given as the
  45 argument, again in a manner similar to the \UNIX{} \program{man}
  46 command.  The synopsis line of a module is the first line of its
  47 documentation string.
  48
  49 You can also use \program{pydoc} to start an HTTP server on the local
  50 machine that will serve documentation to visiting Web browsers.
  51 \program{pydoc} \programopt{-p 1234} will start a HTTP server on port
  52 1234, allowing you to browse the documentation at
  53 \code{http://localhost:1234/} in your preferred Web browser.
  54 \program{pydoc} \programopt{-g} will start the server and additionally
  55 bring up a small \refmodule{Tkinter}-based graphical interface to help
  56 you search for documentation pages.
  57
  58 When \program{pydoc} generates documentation, it uses the current
  59 environment and path to locate modules.  Thus, invoking
  60 \program{pydoc} \programopt{spam} documents precisely the version of
  61 the module you would get if you started the Python interpreter and
  62 typed \samp{import spam}.
  63
  64 Module docs for core modules are assumed to reside in
  65 {}\url{http://www.python.org/doc/current/lib/}.  This can be overridden by
  66 setting the \envvar{PYTHONDOCS} environment variable to a different URL or
  67 to a local directory containing the Library Reference Manual pages.