blob: 0108d798b413582650f15b5e25900802a3f43d64 [file] [log] [blame]
Fred Drake96be5642001-12-18 16:31:44 +00001\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
14The \module{pydoc} module automatically generates documentation from
15Python modules. The documentation can be presented as pages of text
16on the console, served to a Web browser, or saved to HTML files.
17
18The built-in function \function{help()} invokes the online help system
19in the interactive interpreter, which uses \module{pydoc} to generate
20its documentation as text on the console. The same text documentation
21can also be viewed from outside the Python interpreter by running
22\program{pydoc} as a script at the operating system's command prompt.
23For example, running
24
25\begin{verbatim}
26pydoc sys
27\end{verbatim}
28
29at a shell prompt will display documentation on the \refmodule{sys}
30module, 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
32of a function, module, or package, or a dotted reference to a class,
33method, or function within a module or module in a package. If the
34argument to \program{pydoc} looks like a path (that is, it contains the
35path separator for your operating system, such as a slash in \UNIX),
36and refers to an existing Python source file, then documentation is
37produced for that file.
38
39Specifying a \programopt{-w} flag before the argument will cause HTML
40documentation to be written out to a file in the current directory,
41instead of displaying text on the console.
42
43Specifying a \programopt{-k} flag before the argument will search the
44synopsis lines of all available modules for the keyword given as the
45argument, again in a manner similar to the \UNIX{} \program{man}
46command. The synopsis line of a module is the first line of its
47documentation string.
48
49You can also use \program{pydoc} to start an HTTP server on the local
50machine that will serve documentation to visiting Web browsers.
51\program{pydoc} \programopt{-p 1234} will start a HTTP server on port
521234, 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
55bring up a small \refmodule{Tkinter}-based graphical interface to help
56you search for documentation pages.
57
58When \program{pydoc} generates documentation, it uses the current
59environment and path to locate modules. Thus, invoking
60\program{pydoc} \programopt{spam} documents precisely the version of
61the module you would get if you started the Python interpreter and
62typed \samp{import spam}.