cpython/Doc/library/pydoc.rst

73 lines
3.3 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:01 -03:00
: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.
.. note::
In order to find objects and their documentation, :mod:`pydoc` imports the
module(s) to be documented. Therefore, any code on module level will be
executed on that occasion. Use an ``if __name__ == '__main__':`` guard to
only execute code when a file is invoked as a script and not just imported.
Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r86521 | eric.araujo | 2010-11-18 17:38:46 +0100 (jeu., 18 nov. 2010) | 17 lines Fix usage of :option: in the docs (#9312). :option: is used to create a link to an option of python, not to mark up any instance of any arbitrary command-line option. These were changed to ````. For modules which do have a command-line interface, lists of options have been properly marked up with the program/cmdoption directives combo. Options defined in such blocks can be linked to with :option: later in the same file, they won’t link to an option of python. Finally, the markup of command-line fragments in optparse.rst has been cleaned to use ``x`` instead of ``"x"``, keeping that latter form for actual Python strings. Patch by Eli Bendersky and Éric Araujo. ........ r86632 | eric.araujo | 2010-11-21 04:09:17 +0100 (dim., 21 nov. 2010) | 2 lines Style edits in followup to r86521 (#9312) ........ r86823 | eric.araujo | 2010-11-27 00:31:07 +0100 (sam., 27 nov. 2010) | 2 lines Use link-generating markup (see #9312) ........ r86824 | eric.araujo | 2010-11-27 00:46:18 +0100 (sam., 27 nov. 2010) | 2 lines Rewrap long lines + minor edits ........ r87294 | eric.araujo | 2010-12-16 01:07:01 +0100 (jeu., 16 déc. 2010) | 2 lines No need to generate a link for something that’s just above. ........ r87296 | eric.araujo | 2010-12-16 01:23:30 +0100 (jeu., 16 déc. 2010) | 2 lines Advertise “python -m” instead of direct filename. ........ r87300 | eric.araujo | 2010-12-16 02:40:26 +0100 (jeu., 16 déc. 2010) | 2 lines Advertise “python -m test” over test.regrtest (r87296 followup) ........ r87302 | eric.araujo | 2010-12-16 03:10:11 +0100 (jeu., 16 déc. 2010) | 2 lines Add versionadded directive missing from r78983. ........
2010-12-15 23:53:53 -04:00
Specifying a ``-w`` flag before the argument will cause HTML documentation
2007-08-15 11:28:01 -03:00
to be written out to a file in the current directory, instead of displaying text
on the console.
Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r86521 | eric.araujo | 2010-11-18 17:38:46 +0100 (jeu., 18 nov. 2010) | 17 lines Fix usage of :option: in the docs (#9312). :option: is used to create a link to an option of python, not to mark up any instance of any arbitrary command-line option. These were changed to ````. For modules which do have a command-line interface, lists of options have been properly marked up with the program/cmdoption directives combo. Options defined in such blocks can be linked to with :option: later in the same file, they won’t link to an option of python. Finally, the markup of command-line fragments in optparse.rst has been cleaned to use ``x`` instead of ``"x"``, keeping that latter form for actual Python strings. Patch by Eli Bendersky and Éric Araujo. ........ r86632 | eric.araujo | 2010-11-21 04:09:17 +0100 (dim., 21 nov. 2010) | 2 lines Style edits in followup to r86521 (#9312) ........ r86823 | eric.araujo | 2010-11-27 00:31:07 +0100 (sam., 27 nov. 2010) | 2 lines Use link-generating markup (see #9312) ........ r86824 | eric.araujo | 2010-11-27 00:46:18 +0100 (sam., 27 nov. 2010) | 2 lines Rewrap long lines + minor edits ........ r87294 | eric.araujo | 2010-12-16 01:07:01 +0100 (jeu., 16 déc. 2010) | 2 lines No need to generate a link for something that’s just above. ........ r87296 | eric.araujo | 2010-12-16 01:23:30 +0100 (jeu., 16 déc. 2010) | 2 lines Advertise “python -m” instead of direct filename. ........ r87300 | eric.araujo | 2010-12-16 02:40:26 +0100 (jeu., 16 déc. 2010) | 2 lines Advertise “python -m test” over test.regrtest (r87296 followup) ........ r87302 | eric.araujo | 2010-12-16 03:10:11 +0100 (jeu., 16 déc. 2010) | 2 lines Add versionadded directive missing from r78983. ........
2010-12-15 23:53:53 -04:00
Specifying a ``-k`` flag before the argument will search the synopsis
2007-08-15 11:28:01 -03:00
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
Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r86521 | eric.araujo | 2010-11-18 17:38:46 +0100 (jeu., 18 nov. 2010) | 17 lines Fix usage of :option: in the docs (#9312). :option: is used to create a link to an option of python, not to mark up any instance of any arbitrary command-line option. These were changed to ````. For modules which do have a command-line interface, lists of options have been properly marked up with the program/cmdoption directives combo. Options defined in such blocks can be linked to with :option: later in the same file, they won’t link to an option of python. Finally, the markup of command-line fragments in optparse.rst has been cleaned to use ``x`` instead of ``"x"``, keeping that latter form for actual Python strings. Patch by Eli Bendersky and Éric Araujo. ........ r86632 | eric.araujo | 2010-11-21 04:09:17 +0100 (dim., 21 nov. 2010) | 2 lines Style edits in followup to r86521 (#9312) ........ r86823 | eric.araujo | 2010-11-27 00:31:07 +0100 (sam., 27 nov. 2010) | 2 lines Use link-generating markup (see #9312) ........ r86824 | eric.araujo | 2010-11-27 00:46:18 +0100 (sam., 27 nov. 2010) | 2 lines Rewrap long lines + minor edits ........ r87294 | eric.araujo | 2010-12-16 01:07:01 +0100 (jeu., 16 déc. 2010) | 2 lines No need to generate a link for something that’s just above. ........ r87296 | eric.araujo | 2010-12-16 01:23:30 +0100 (jeu., 16 déc. 2010) | 2 lines Advertise “python -m” instead of direct filename. ........ r87300 | eric.araujo | 2010-12-16 02:40:26 +0100 (jeu., 16 déc. 2010) | 2 lines Advertise “python -m test” over test.regrtest (r87296 followup) ........ r87302 | eric.araujo | 2010-12-16 03:10:11 +0100 (jeu., 16 déc. 2010) | 2 lines Add versionadded directive missing from r78983. ........
2010-12-15 23:53:53 -04:00
that will serve documentation to visiting Web browsers. :program:`pydoc -p 1234`
will start a HTTP server on port 1234, allowing you to browse
2007-08-15 11:28:01 -03:00
the documentation at ``http://localhost:1234/`` in your preferred Web browser.
Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r86521 | eric.araujo | 2010-11-18 17:38:46 +0100 (jeu., 18 nov. 2010) | 17 lines Fix usage of :option: in the docs (#9312). :option: is used to create a link to an option of python, not to mark up any instance of any arbitrary command-line option. These were changed to ````. For modules which do have a command-line interface, lists of options have been properly marked up with the program/cmdoption directives combo. Options defined in such blocks can be linked to with :option: later in the same file, they won’t link to an option of python. Finally, the markup of command-line fragments in optparse.rst has been cleaned to use ``x`` instead of ``"x"``, keeping that latter form for actual Python strings. Patch by Eli Bendersky and Éric Araujo. ........ r86632 | eric.araujo | 2010-11-21 04:09:17 +0100 (dim., 21 nov. 2010) | 2 lines Style edits in followup to r86521 (#9312) ........ r86823 | eric.araujo | 2010-11-27 00:31:07 +0100 (sam., 27 nov. 2010) | 2 lines Use link-generating markup (see #9312) ........ r86824 | eric.araujo | 2010-11-27 00:46:18 +0100 (sam., 27 nov. 2010) | 2 lines Rewrap long lines + minor edits ........ r87294 | eric.araujo | 2010-12-16 01:07:01 +0100 (jeu., 16 déc. 2010) | 2 lines No need to generate a link for something that’s just above. ........ r87296 | eric.araujo | 2010-12-16 01:23:30 +0100 (jeu., 16 déc. 2010) | 2 lines Advertise “python -m” instead of direct filename. ........ r87300 | eric.araujo | 2010-12-16 02:40:26 +0100 (jeu., 16 déc. 2010) | 2 lines Advertise “python -m test” over test.regrtest (r87296 followup) ........ r87302 | eric.araujo | 2010-12-16 03:10:11 +0100 (jeu., 16 déc. 2010) | 2 lines Add versionadded directive missing from r78983. ........
2010-12-15 23:53:53 -04:00
:program:`pydoc -g` will start the server and additionally bring up a
2007-08-15 11:28:01 -03:00
small :mod:`Tkinter`\ -based graphical interface to help you search for
documentation pages.
When :program:`pydoc` generates documentation, it uses the current environment
Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r86521 | eric.araujo | 2010-11-18 17:38:46 +0100 (jeu., 18 nov. 2010) | 17 lines Fix usage of :option: in the docs (#9312). :option: is used to create a link to an option of python, not to mark up any instance of any arbitrary command-line option. These were changed to ````. For modules which do have a command-line interface, lists of options have been properly marked up with the program/cmdoption directives combo. Options defined in such blocks can be linked to with :option: later in the same file, they won’t link to an option of python. Finally, the markup of command-line fragments in optparse.rst has been cleaned to use ``x`` instead of ``"x"``, keeping that latter form for actual Python strings. Patch by Eli Bendersky and Éric Araujo. ........ r86632 | eric.araujo | 2010-11-21 04:09:17 +0100 (dim., 21 nov. 2010) | 2 lines Style edits in followup to r86521 (#9312) ........ r86823 | eric.araujo | 2010-11-27 00:31:07 +0100 (sam., 27 nov. 2010) | 2 lines Use link-generating markup (see #9312) ........ r86824 | eric.araujo | 2010-11-27 00:46:18 +0100 (sam., 27 nov. 2010) | 2 lines Rewrap long lines + minor edits ........ r87294 | eric.araujo | 2010-12-16 01:07:01 +0100 (jeu., 16 déc. 2010) | 2 lines No need to generate a link for something that’s just above. ........ r87296 | eric.araujo | 2010-12-16 01:23:30 +0100 (jeu., 16 déc. 2010) | 2 lines Advertise “python -m” instead of direct filename. ........ r87300 | eric.araujo | 2010-12-16 02:40:26 +0100 (jeu., 16 déc. 2010) | 2 lines Advertise “python -m test” over test.regrtest (r87296 followup) ........ r87302 | eric.araujo | 2010-12-16 03:10:11 +0100 (jeu., 16 déc. 2010) | 2 lines Add versionadded directive missing from r78983. ........
2010-12-15 23:53:53 -04:00
and path to locate modules. Thus, invoking :program:`pydoc spam`
2007-08-15 11:28:01 -03:00
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
2008-01-21 13:13:03 -04:00
http://docs.python.org/library/. This can be overridden by setting the
2007-08-15 11:28:01 -03:00
:envvar:`PYTHONDOCS` environment variable to a different URL or to a local
directory containing the Library Reference Manual pages.