/Doc/library/pydoc.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 72 lines · 55 code · 17 blank · 0 comment · 0 complexity · a2ef6c9c6cac030e5ae2616397b24611 MD5 · raw file

  1. :mod:`pydoc` --- Documentation generator and online help system
  2. ===============================================================
  3. .. module:: pydoc
  4. :synopsis: Documentation generator and online help system.
  5. .. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
  6. .. sectionauthor:: Ka-Ping Yee <ping@lfw.org>
  7. .. versionadded:: 2.1
  8. .. index::
  9. single: documentation; generation
  10. single: documentation; online
  11. single: help; online
  12. The :mod:`pydoc` module automatically generates documentation from Python
  13. modules. The documentation can be presented as pages of text on the console,
  14. served to a Web browser, or saved to HTML files.
  15. The built-in function :func:`help` invokes the online help system in the
  16. interactive interpreter, which uses :mod:`pydoc` to generate its documentation
  17. as text on the console. The same text documentation can also be viewed from
  18. outside the Python interpreter by running :program:`pydoc` as a script at the
  19. operating system's command prompt. For example, running ::
  20. pydoc sys
  21. at a shell prompt will display documentation on the :mod:`sys` module, in a
  22. style similar to the manual pages shown by the Unix :program:`man` command. The
  23. argument to :program:`pydoc` can be the name of a function, module, or package,
  24. or a dotted reference to a class, method, or function within a module or module
  25. in a package. If the argument to :program:`pydoc` looks like a path (that is,
  26. it contains the path separator for your operating system, such as a slash in
  27. Unix), and refers to an existing Python source file, then documentation is
  28. produced for that file.
  29. .. note::
  30. In order to find objects and their documentation, :mod:`pydoc` imports the
  31. module(s) to be documented. Therefore, any code on module level will be
  32. executed on that occasion. Use an ``if __name__ == '__main__':`` guard to
  33. only execute code when a file is invoked as a script and not just imported.
  34. Specifying a :option:`-w` flag before the argument will cause HTML documentation
  35. to be written out to a file in the current directory, instead of displaying text
  36. on the console.
  37. Specifying a :option:`-k` flag before the argument will search the synopsis
  38. lines of all available modules for the keyword given as the argument, again in a
  39. manner similar to the Unix :program:`man` command. The synopsis line of a
  40. module is the first line of its documentation string.
  41. You can also use :program:`pydoc` to start an HTTP server on the local machine
  42. that will serve documentation to visiting Web browsers. :program:`pydoc`
  43. :option:`-p 1234` will start a HTTP server on port 1234, allowing you to browse
  44. the documentation at ``http://localhost:1234/`` in your preferred Web browser.
  45. :program:`pydoc` :option:`-g` will start the server and additionally bring up a
  46. small :mod:`Tkinter`\ -based graphical interface to help you search for
  47. documentation pages.
  48. When :program:`pydoc` generates documentation, it uses the current environment
  49. and path to locate modules. Thus, invoking :program:`pydoc` :option:`spam`
  50. documents precisely the version of the module you would get if you started the
  51. Python interpreter and typed ``import spam``.
  52. Module docs for core modules are assumed to reside in
  53. http://docs.python.org/library/. This can be overridden by setting the
  54. :envvar:`PYTHONDOCS` environment variable to a different URL or to a local
  55. directory containing the Library Reference Manual pages.