Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`pydoc` --- Documentation generator and online help system |
| 2 | =============================================================== |
| 3 | |
| 4 | .. module:: pydoc |
| 5 | :synopsis: Documentation generator and online help system. |
| 6 | .. moduleauthor:: Ka-Ping Yee <ping@lfw.org> |
| 7 | .. sectionauthor:: Ka-Ping Yee <ping@lfw.org> |
| 8 | |
| 9 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | .. index:: |
| 11 | single: documentation; generation |
| 12 | single: documentation; online |
| 13 | single: help; online |
| 14 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 15 | **Source code:** :source:`Lib/pydoc.py` |
| 16 | |
| 17 | -------------- |
| 18 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 19 | The :mod:`pydoc` module automatically generates documentation from Python |
| 20 | modules. The documentation can be presented as pages of text on the console, |
| 21 | served to a Web browser, or saved to HTML files. |
| 22 | |
| 23 | The built-in function :func:`help` invokes the online help system in the |
| 24 | interactive interpreter, which uses :mod:`pydoc` to generate its documentation |
| 25 | as text on the console. The same text documentation can also be viewed from |
| 26 | outside the Python interpreter by running :program:`pydoc` as a script at the |
| 27 | operating system's command prompt. For example, running :: |
| 28 | |
| 29 | pydoc sys |
| 30 | |
| 31 | at a shell prompt will display documentation on the :mod:`sys` module, in a |
| 32 | style similar to the manual pages shown by the Unix :program:`man` command. The |
| 33 | argument to :program:`pydoc` can be the name of a function, module, or package, |
| 34 | or a dotted reference to a class, method, or function within a module or module |
| 35 | in a package. If the argument to :program:`pydoc` looks like a path (that is, |
| 36 | it contains the path separator for your operating system, such as a slash in |
| 37 | Unix), and refers to an existing Python source file, then documentation is |
| 38 | produced for that file. |
| 39 | |
Benjamin Peterson | da10d3b | 2009-01-01 00:23:30 +0000 | [diff] [blame] | 40 | .. note:: |
| 41 | |
| 42 | In order to find objects and their documentation, :mod:`pydoc` imports the |
| 43 | module(s) to be documented. Therefore, any code on module level will be |
| 44 | executed on that occasion. Use an ``if __name__ == '__main__':`` guard to |
| 45 | only execute code when a file is invoked as a script and not just imported. |
| 46 | |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 47 | Specifying a ``-w`` flag before the argument will cause HTML documentation |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | to be written out to a file in the current directory, instead of displaying text |
| 49 | on the console. |
| 50 | |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 51 | Specifying a ``-k`` flag before the argument will search the synopsis |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 52 | lines of all available modules for the keyword given as the argument, again in a |
| 53 | manner similar to the Unix :program:`man` command. The synopsis line of a |
| 54 | module is the first line of its documentation string. |
| 55 | |
| 56 | You can also use :program:`pydoc` to start an HTTP server on the local machine |
Nick Coghlan | 7bb30b7 | 2010-12-03 09:29:11 +0000 | [diff] [blame] | 57 | that will serve documentation to visiting Web browsers. :program:`pydoc -p 1234` |
| 58 | will start a HTTP server on port 1234, allowing you to browse the |
| 59 | documentation at ``http://localhost:1234/`` in your preferred Web browser. |
| 60 | Specifying ``0`` as the port number will select an arbitrary unused port. |
| 61 | |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 62 | :program:`pydoc -g` will start the server and additionally bring up a |
Ezio Melotti | 1a263ad | 2010-03-14 09:51:37 +0000 | [diff] [blame] | 63 | small :mod:`tkinter`\ -based graphical interface to help you search for |
Nick Coghlan | 7bb30b7 | 2010-12-03 09:29:11 +0000 | [diff] [blame] | 64 | documentation pages. The ``-g`` option is deprecated, since the server can |
| 65 | now be controlled directly from HTTP clients. |
| 66 | |
| 67 | :program:`pydoc -b` will start the server and additionally open a web |
| 68 | browser to a module index page. Each served page has a navigation bar at the |
| 69 | top where you can *Get* help on an individual item, *Search* all modules with a |
| 70 | keyword in their synopsis line, and go to the *Module index*, *Topics* and |
| 71 | *Keywords* pages. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | |
| 73 | When :program:`pydoc` generates documentation, it uses the current environment |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 74 | and path to locate modules. Thus, invoking :program:`pydoc spam` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | documents precisely the version of the module you would get if you started the |
| 76 | Python interpreter and typed ``import spam``. |
| 77 | |
| 78 | Module docs for core modules are assumed to reside in |
Alexander Belopolsky | a47bbf5 | 2010-11-18 01:52:54 +0000 | [diff] [blame] | 79 | ``http://docs.python.org/X.Y/library/`` where ``X`` and ``Y`` are the |
| 80 | major and minor version numbers of the Python interpreter. This can |
| 81 | be overridden by setting the :envvar:`PYTHONDOCS` environment variable |
| 82 | to a different URL or to a local directory containing the Library |
| 83 | Reference Manual pages. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
Nick Coghlan | 7bb30b7 | 2010-12-03 09:29:11 +0000 | [diff] [blame] | 85 | .. versionchanged:: 3.2 |
Georg Brandl | 34e9fc2 | 2010-12-03 09:45:33 +0000 | [diff] [blame] | 86 | Added the ``-b`` option, deprecated the ``-g`` option. |