mirror of
https://github.com/python/cpython.git
synced 2025-11-03 23:21:29 +00:00
63 lines
2.8 KiB
TeX
63 lines
2.8 KiB
TeX
|
\section{\module{pydoc} ---
|
||
|
|
Documentation generator and online help system}
|
||
|
|
|
||
|
|
\declaremodule{standard}{pydoc}
|
||
|
|
\modulesynopsis{Documentation generator and online help system.}
|
||
|
|
\moduleauthor{Ka-Ping Yee}{ping@lfw.org}
|
||
|
|
\sectionauthor{Ka-Ping Yee}{ping@lfw.org}
|
||
|
|
|
||
|
|
\versionadded{2.1}
|
||
|
|
\index{documentation!generation}
|
||
|
|
\index{documentation!online}
|
||
|
|
\index{help!online}
|
||
|
|
|
||
|
|
The \module{pydoc} module automatically generates documentation from
|
||
|
|
Python modules. The documentation can be presented as pages of text
|
||
|
|
on the console, served to a Web browser, or saved to HTML files.
|
||
|
|
|
||
|
|
The built-in function \function{help()} invokes the online help system
|
||
|
|
in the interactive interpreter, which uses \module{pydoc} to generate
|
||
|
|
its documentation as text on the console. The same text documentation
|
||
|
|
can also be viewed from outside the Python interpreter by running
|
||
|
|
\program{pydoc} as a script at the operating system's command prompt.
|
||
|
|
For example, running
|
||
|
|
|
||
|
|
\begin{verbatim}
|
||
|
|
pydoc sys
|
||
|
|
\end{verbatim}
|
||
|
|
|
||
|
|
at a shell prompt will display documentation on the \refmodule{sys}
|
||
|
|
module, in a style similar to the manual pages shown by the \UNIX{}
|
||
|
|
\program{man} command. The argument to \program{pydoc} can be the name
|
||
|
|
of a function, module, or package, or a dotted reference to a class,
|
||
|
|
method, or function within a module or module in a package. If the
|
||
|
|
argument to \program{pydoc} looks like a path (that is, it contains the
|
||
|
|
path separator for your operating system, such as a slash in \UNIX),
|
||
|
|
and refers to an existing Python source file, then documentation is
|
||
|
|
produced for that file.
|
||
|
|
|
||
|
|
Specifying a \programopt{-w} flag before the argument will cause HTML
|
||
|
|
documentation to be written out to a file in the current directory,
|
||
|
|
instead of displaying text on the console.
|
||
|
|
|
||
|
|
Specifying a \programopt{-k} flag before the argument will search the
|
||
|
|
synopsis lines of all available modules for the keyword given as the
|
||
|
|
argument, again in a manner similar to the \UNIX{} \program{man}
|
||
|
|
command. The synopsis line of a module is the first line of its
|
||
|
|
documentation string.
|
||
|
|
|
||
|
|
You can also use \program{pydoc} to start an HTTP server on the local
|
||
|
|
machine that will serve documentation to visiting Web browsers.
|
||
|
|
\program{pydoc} \programopt{-p 1234} will start a HTTP server on port
|
||
|
|
1234, allowing you to browse the documentation at
|
||
|
|
\code{http://localhost:1234/} in your preferred Web browser.
|
||
|
|
\program{pydoc} \programopt{-g} will start the server and additionally
|
||
|
|
bring up a small \refmodule{Tkinter}-based graphical interface to help
|
||
|
|
you search for documentation pages.
|
||
|
|
|
||
|
|
When \program{pydoc} generates documentation, it uses the current
|
||
|
|
environment and path to locate modules. Thus, invoking
|
||
|
|
\program{pydoc} \programopt{spam} documents precisely the version of
|
||
|
|
the module you would get if you started the Python interpreter and
|
||
|
|
typed \samp{import spam}.
|