/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
18The :mod:`pydoc` module automatically generates documentation from Python
19modules.  The documentation can be presented as pages of text on the console,
20served to a Web browser, or saved to HTML files.
21
22The built-in function :func:`help` invokes the online help system in the
23interactive interpreter, which uses :mod:`pydoc` to generate its documentation
24as text on the console.  The same text documentation can also be viewed from
25outside the Python interpreter by running :program:`pydoc` as a script at the
26operating system's command prompt. For example, running ::
27
28   pydoc sys
29
30at a shell prompt will display documentation on the :mod:`sys` module, in a
31style similar to the manual pages shown by the Unix :program:`man` command.  The
32argument to :program:`pydoc` can be the name of a function, module, or package,
33or a dotted reference to a class, method, or function within a module or module
34in a package.  If the argument to :program:`pydoc` looks like a path (that is,
35it contains the path separator for your operating system, such as a slash in
36Unix), and refers to an existing Python source file, then documentation is
37produced 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
46Specifying a :option:`-w` flag before the argument will cause HTML documentation
47to be written out to a file in the current directory, instead of displaying text
48on the console.
49
50Specifying a :option:`-k` flag before the argument will search the synopsis
51lines of all available modules for the keyword given as the argument, again in a
52manner similar to the Unix :program:`man` command.  The synopsis line of a
53module is the first line of its documentation string.
54
55You can also use :program:`pydoc` to start an HTTP server on the local machine
56that 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
58the documentation at ``http://localhost:1234/`` in your preferred Web browser.
59:program:`pydoc` :option:`-g` will start the server and additionally bring up a
60small :mod:`Tkinter`\ -based graphical interface to help you search for
61documentation pages.
62
63When :program:`pydoc` generates documentation, it uses the current environment
64and path to locate modules.  Thus, invoking :program:`pydoc` :option:`spam`
65documents precisely the version of the module you would get if you started the
66Python interpreter and typed ``import spam``.
67
68Module docs for core modules are assumed to reside in
69http://docs.python.org/library/.  This can be overridden by setting the
70:envvar:`PYTHONDOCS` environment variable to a different URL or to a local
71directory containing the Library Reference Manual pages.
72