diff options
Diffstat (limited to 'Doc/library/pydoc.rst')
| -rw-r--r-- | Doc/library/pydoc.rst | 65 |
1 files changed, 65 insertions, 0 deletions
diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst new file mode 100644 index 0000000000..2df127c0af --- /dev/null +++ b/Doc/library/pydoc.rst @@ -0,0 +1,65 @@ + +:mod:`pydoc` --- Documentation generator and online help system +=============================================================== + +.. module:: pydoc + :synopsis: Documentation generator and online help system. +.. moduleauthor:: Ka-Ping Yee <ping@lfw.org> +.. sectionauthor:: Ka-Ping Yee <ping@lfw.org> + + +.. versionadded:: 2.1 + +.. index:: + single: documentation; generation + single: documentation; online + single: help; online + +The :mod:`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 :func:`help` invokes the online help system in the +interactive interpreter, which uses :mod:`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 :: + + pydoc sys + +at a shell prompt will display documentation on the :mod:`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 :option:`-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 :option:`-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` +:option:`-p 1234` will start a HTTP server on port 1234, allowing you to browse +the documentation at ``http://localhost:1234/`` in your preferred Web browser. +:program:`pydoc` :option:`-g` will start the server and additionally bring up a +small :mod:`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` :option:`spam` +documents precisely the version of the module you would get if you started the +Python interpreter and typed ``import spam``. + +Module docs for core modules are assumed to reside in +http://www.python.org/doc/current/lib/. This can be overridden by setting the +:envvar:`PYTHONDOCS` environment variable to a different URL or to a local +directory containing the Library Reference Manual pages. + |