Anonymous avatar Anonymous committed 17ca679

Add missing synopses for library modules.

Comments (0)

Files changed (43)

 * split very large files and add toctrees
 * integrate standalone HOWTOs
 * find out which files get "comments disabled" metadata
-* add synopses for each module
 * write "About these documents"
 * finish "Documenting Python"
 * extend copyright.rst

Doc-26/library/cgi.rst

 ================================================
 
 .. module:: cgi
-
-
+   :synopsis: Helpers for running Python scripts via the Common Gateway Interface.
 
 
 .. index::
    pair: HTTP; protocol
    pair: MIME; headers
    single: URL
-
-.. index:: single: Common Gateway Interface
+   single: Common Gateway Interface
 
 Support module for Common Gateway Interface (CGI) scripts.
 
-.. % 
-
 This module defines a number of utilities for use by CGI scripts written in
 Python.
 

Doc-26/library/code.rst

 ========================================
 
 .. module:: code
-
+   :synopsis: Facilities to implement read-eval-print loops.
 
 
 

Doc-26/library/cookielib.rst

 =====================================================
 
 .. module:: cookielib
+   :synopsis: Classes for automatic handling of HTTP cookies.
 .. moduleauthor:: John J. Lee <jjl@pobox.com>
 .. sectionauthor:: John J. Lee <jjl@pobox.com>
 

Doc-26/library/doctest.rst

-
 :mod:`doctest` --- Test interactive Python examples
 ===================================================
 
 .. module:: doctest
+   :synopsis: Test pieces of code within docstrings.
 .. moduleauthor:: Tim Peters <tim@python.org>
 .. sectionauthor:: Tim Peters <tim@python.org>
 .. sectionauthor:: Moshe Zadka <moshez@debian.org>
 .. sectionauthor:: Edward Loper <edloper@users.sourceforge.net>
 
 
-
-
 The :mod:`doctest` module searches for pieces of text that look like interactive
 Python sessions, and then executes those sessions to verify that they work
 exactly as shown.  There are several common ways to use doctest:

Doc-26/library/email.mime.rst

 :mod:`email`: Creating email and MIME objects from scratch
 ----------------------------------------------------------
 
-.. module:: email.mime.text
+.. module:: email.mime
+   :synopsis: Build MIME messages. 
 
 
 Ordinarily, you get a message object structure by passing a file or some text to

Doc-26/library/fileinput.rst

-
 :mod:`fileinput` --- Iterate over lines from multiple input streams
 ===================================================================
 
 .. module:: fileinput
+   :synopsis: Loop over standard input or a list of files.
 .. moduleauthor:: Guido van Rossum <guido@python.org>
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 
 
-
-
 This module implements a helper class and functions to quickly write a loop over
 standard input or a list of files.
 

Doc-26/library/functools.rst

-
-:mod:`functools` --- Higher order functions and operations on callable objects.
-===============================================================================
+:mod:`functools` --- Higher order functions and operations on callable objects
+==============================================================================
 
 .. module:: functools
+   :synopsis: Higher order functions and operations on callable objects.
 .. moduleauthor:: Peter Harris <scav@blueyonder.co.uk>
 .. moduleauthor:: Raymond Hettinger <python@rcn.com>
 .. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
 .. sectionauthor:: Peter Harris <scav@blueyonder.co.uk>
 
 
-.. % standard library, in Python
-
-
-
 .. versionadded:: 2.5
 
 The :mod:`functools` module is for higher-order functions: functions that act on

Doc-26/library/logging.rst

-
 :mod:`logging` --- Logging facility for Python
 ==============================================
 
 .. module:: logging
+   :synopsis: Flexible error logging system for applications.
 
 
 .. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com>

Doc-26/library/mailcap.rst

-
-:mod:`mailcap` --- Mailcap file handling.
-=========================================
+:mod:`mailcap` --- Mailcap file handling
+========================================
 
 .. module:: mailcap
-
+   :synopsis: Mailcap file handling.
 
 
 

Doc-26/library/mimewriter.rst

-
 :mod:`MimeWriter` --- Generic MIME file writer
 ==============================================
 
 .. module:: MimeWriter
-
+   :synopsis: Write MIME format files.
 
 .. sectionauthor:: Christopher G. Petrilli <petrilli@amber.org>
 

Doc-26/library/operator.rst

-
-:mod:`operator` --- Standard operators as functions.
-====================================================
+:mod:`operator` --- Standard operators as functions
+===================================================
 
 .. module:: operator
+   :synopsis: Functions corresponding to the standard operators.
 .. sectionauthor:: Skip Montanaro <skip@automatrix.com>
 
 
 
-
 The :mod:`operator` module exports a set of functions implemented in C
 corresponding to the intrinsic operators of Python.  For example,
 ``operator.add(x, y)`` is equivalent to the expression ``x+y``.  The function

Doc-26/library/os.path.rst

 ================================================
 
 .. module:: os.path
-
-
+   :synopsis: Operations on pathnames.
 
 
 .. index:: single: path; operations

Doc-26/library/profile.rst

 
    The :class:`Stats` class is defined in the :mod:`pstats` module.
 
+
 .. module:: pstats
-
-
-.. % now switch modules....
-.. % (This \stmodindex use may be hard to change ;-( )
+   :synopsis: Statistics object for use with the profiler.
 
 
 .. class:: Stats(filename[, stream=sys.stdout[, ...]])

Doc-26/library/py_compile.rst

-
 :mod:`py_compile` --- Compile Python source files
 =================================================
 
 .. module:: py_compile
-
+   :synopsis: Generate byte-code files from Python source files.
 
 .. % Documentation based on module docstrings, by Fred L. Drake, Jr.
 .. % <fdrake@acm.org>

Doc-26/library/re.rst

 ===========================================
 
 .. module:: re
+   :synopsis: Regular expression operations.
 .. moduleauthor:: Fredrik Lundh <fredrik@pythonware.com>
 .. sectionauthor:: Andrew M. Kuchling <amk@amk.ca>
 

Doc-26/library/runpy.rst

-
-:mod:`runpy` --- Locating and executing Python modules.
-=======================================================
+:mod:`runpy` --- Locating and executing Python modules
+======================================================
 
 .. module:: runpy
+   :synopsis: Locate and run Python modules without importing them first.
 .. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
 
 
-.. % standard library, in Python
-
-
-
 .. versionadded:: 2.5
 
 The :mod:`runpy` module is used to locate and run Python modules without

Doc-26/library/smtpd.rst

-
 :mod:`smtpd` --- SMTP Server
 ============================
 
 .. module:: smtpd
-
+   :synopsis: A SMTP server implementation in Python.
 
 .. moduleauthor:: Barry Warsaw <barry@zope.com>
 .. sectionauthor:: Moshe Zadka <moshez@moshez.org>

Doc-26/library/struct.rst

 =========================================================
 
 .. module:: struct
-
-
-
+   :synopsis: Interpret strings as packed binary data.
 
 .. index::
    pair: C; structures

Doc-26/library/urllib2.rst

-
 :mod:`urllib2` --- extensible library for opening URLs
 ======================================================
 
 .. module:: urllib2
+   :synopsis: Next generation URL opening library.
 .. moduleauthor:: Jeremy Hylton <jhylton@users.sourceforge.net>
 .. sectionauthor:: Moshe Zadka <moshez@users.sourceforge.net>
 
 
-
-
 The :mod:`urllib2` module defines functions and classes which help in opening
 URLs (mostly HTTP) in a complex world --- basic and digest authentication,
 redirections, cookies and more.

Doc-26/library/urlparse.rst

-
 :mod:`urlparse` --- Parse URLs into components
 ==============================================
 
 .. module:: urlparse
-
-
+   :synopsis: Parse URLs into or assemble them from components.
 
 
 .. index::

Doc-26/library/wsgiref.rst

-
 :mod:`wsgiref` --- WSGI Utilities and Reference Implementation
 ==============================================================
 
 .. module:: wsgiref
-   :synopsis: WSGI Utilities and Reference Implementation
+   :synopsis: WSGI Utilities and Reference Implementation.
 .. moduleauthor:: Phillip J. Eby <pje@telecommunity.com>
 .. sectionauthor:: Phillip J. Eby <pje@telecommunity.com>
 
 -------------------------------------------------
 
 .. module:: wsgiref.util
+   :synopsis: WSGI environment utilities.
 
 
 This module provides a variety of utility functions for working with WSGI
 ----------------------------------------------------
 
 .. module:: wsgiref.headers
+   :synopsis: WSGI response header tools.
 
 
 This module provides a single class, :class:`Headers`, for convenient
 ---------------------------------------------------------
 
 .. module:: wsgiref.simple_server
+   :synopsis: A simple WSGI HTTP server.
 
 
 This module implements a simple HTTP server (based on :mod:`BaseHTTPServer`)
 :mod:`wsgiref.util`.)
 
 
-.. function:: make_server(host, port, app [, server_class=:class:`WSGIServer` [, handler_class=:class:`WSGIRequestHandler`]])
+.. function:: make_server(host, port, app [, server_class=WSGIServer [, handler_class=:class:`WSGIRequestHandler`]])
 
    Create a new WSGI server listening on *host* and *port*, accepting connections
    for *app*.  The return value is an instance of the supplied *server_class*, and
       interface.
 
 
-:mod:`wsgiref.validate` -- WSGI conformance checker
----------------------------------------------------
+:mod:`wsgiref.validate` --- WSGI conformance checker
+----------------------------------------------------
 
 .. module:: wsgiref.validate
+   :synopsis: WSGI conformance checker.
 
 
 When creating new WSGI application objects, frameworks, servers, or middleware,
 ------------------------------------------------------
 
 .. module:: wsgiref.handlers
+   :synopsis: WSGI server/gateway base classes.
 
 
 This module provides base handler classes for implementing WSGI servers and
 * split very large files and add toctrees
 * integrate standalone HOWTOs
 * find out which files get "comments disabled" metadata
-* add synopses for each module
 * write "About these documents"
 * finish "Documenting Python"
 * extend copyright.rst

Doc-3k/library/cgi.rst

 ================================================
 
 .. module:: cgi
-
-
+   :synopsis: Helpers for running Python scripts via the Common Gateway Interface.
 
 
 .. index::
    pair: HTTP; protocol
    pair: MIME; headers
    single: URL
-
-.. index:: single: Common Gateway Interface
+   single: Common Gateway Interface
 
 Support module for Common Gateway Interface (CGI) scripts.
 
-.. % 
-
 This module defines a number of utilities for use by CGI scripts written in
 Python.
 

Doc-3k/library/code.rst

 ========================================
 
 .. module:: code
-
+   :synopsis: Facilities to implement read-eval-print loops.
 
 
 

Doc-3k/library/cookielib.rst

 =====================================================
 
 .. module:: cookielib
+   :synopsis: Classes for automatic handling of HTTP cookies.
 .. moduleauthor:: John J. Lee <jjl@pobox.com>
 .. sectionauthor:: John J. Lee <jjl@pobox.com>
 

Doc-3k/library/doctest.rst

-
 :mod:`doctest` --- Test interactive Python examples
 ===================================================
 
 .. module:: doctest
+   :synopsis: Test pieces of code within docstrings.
 .. moduleauthor:: Tim Peters <tim@python.org>
 .. sectionauthor:: Tim Peters <tim@python.org>
 .. sectionauthor:: Moshe Zadka <moshez@debian.org>
 .. sectionauthor:: Edward Loper <edloper@users.sourceforge.net>
 
 
-
-
 The :mod:`doctest` module searches for pieces of text that look like interactive
 Python sessions, and then executes those sessions to verify that they work
 exactly as shown.  There are several common ways to use doctest:

Doc-3k/library/email.mime.rst

 :mod:`email`: Creating email and MIME objects from scratch
 ----------------------------------------------------------
 
-.. module:: email.mime.text
+.. module:: email.mime
+   :synopsis: Build MIME messages. 
 
 
 Ordinarily, you get a message object structure by passing a file or some text to

Doc-3k/library/fileinput.rst

-
 :mod:`fileinput` --- Iterate over lines from multiple input streams
 ===================================================================
 
 .. module:: fileinput
+   :synopsis: Loop over standard input or a list of files.
 .. moduleauthor:: Guido van Rossum <guido@python.org>
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 
 
-
-
 This module implements a helper class and functions to quickly write a loop over
 standard input or a list of files.
 

Doc-3k/library/functools.rst

-
-:mod:`functools` --- Higher order functions and operations on callable objects.
-===============================================================================
+:mod:`functools` --- Higher order functions and operations on callable objects
+==============================================================================
 
 .. module:: functools
+   :synopsis: Higher order functions and operations on callable objects.
 .. moduleauthor:: Peter Harris <scav@blueyonder.co.uk>
 .. moduleauthor:: Raymond Hettinger <python@rcn.com>
 .. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
 .. sectionauthor:: Peter Harris <scav@blueyonder.co.uk>
 
 
-.. % standard library, in Python
-
-
-
 .. versionadded:: 2.5
 
 The :mod:`functools` module is for higher-order functions: functions that act on

Doc-3k/library/logging.rst

-
 :mod:`logging` --- Logging facility for Python
 ==============================================
 
 .. module:: logging
+   :synopsis: Flexible error logging system for applications.
 
 
 .. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com>

Doc-3k/library/mailcap.rst

-
-:mod:`mailcap` --- Mailcap file handling.
-=========================================
+:mod:`mailcap` --- Mailcap file handling
+========================================
 
 .. module:: mailcap
-
+   :synopsis: Mailcap file handling.
 
 
 

Doc-3k/library/operator.rst

-
-:mod:`operator` --- Standard operators as functions.
-====================================================
+:mod:`operator` --- Standard operators as functions
+===================================================
 
 .. module:: operator
+   :synopsis: Functions corresponding to the standard operators.
 .. sectionauthor:: Skip Montanaro <skip@automatrix.com>
 
 
 
-
 The :mod:`operator` module exports a set of functions implemented in C
 corresponding to the intrinsic operators of Python.  For example,
 ``operator.add(x, y)`` is equivalent to the expression ``x+y``.  The function

Doc-3k/library/os.path.rst

 ================================================
 
 .. module:: os.path
-
-
+   :synopsis: Operations on pathnames.
 
 
 .. index:: single: path; operations

Doc-3k/library/profile.rst

 
    The :class:`Stats` class is defined in the :mod:`pstats` module.
 
+
 .. module:: pstats
-
-
-.. % now switch modules....
-.. % (This \stmodindex use may be hard to change ;-( )
+   :synopsis: Statistics object for use with the profiler.
 
 
 .. class:: Stats(filename[, stream=sys.stdout[, ...]])

Doc-3k/library/py_compile.rst

-
 :mod:`py_compile` --- Compile Python source files
 =================================================
 
 .. module:: py_compile
-
+   :synopsis: Generate byte-code files from Python source files.
 
 .. % Documentation based on module docstrings, by Fred L. Drake, Jr.
 .. % <fdrake@acm.org>

Doc-3k/library/re.rst

 ===========================================
 
 .. module:: re
+   :synopsis: Regular expression operations.
 .. moduleauthor:: Fredrik Lundh <fredrik@pythonware.com>
 .. sectionauthor:: Andrew M. Kuchling <amk@amk.ca>
 

Doc-3k/library/runpy.rst

-
-:mod:`runpy` --- Locating and executing Python modules.
-=======================================================
+:mod:`runpy` --- Locating and executing Python modules
+======================================================
 
 .. module:: runpy
+   :synopsis: Locate and run Python modules without importing them first.
 .. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
 
 
-.. % standard library, in Python
-
-
-
 .. versionadded:: 2.5
 
 The :mod:`runpy` module is used to locate and run Python modules without

Doc-3k/library/smtpd.rst

-
 :mod:`smtpd` --- SMTP Server
 ============================
 
 .. module:: smtpd
-
+   :synopsis: A SMTP server implementation in Python.
 
 .. moduleauthor:: Barry Warsaw <barry@zope.com>
 .. sectionauthor:: Moshe Zadka <moshez@moshez.org>

Doc-3k/library/struct.rst

 =========================================================
 
 .. module:: struct
-
-
-
+   :synopsis: Interpret strings as packed binary data.
 
 .. index::
    pair: C; structures

Doc-3k/library/urllib2.rst

-
 :mod:`urllib2` --- extensible library for opening URLs
 ======================================================
 
 .. module:: urllib2
+   :synopsis: Next generation URL opening library.
 .. moduleauthor:: Jeremy Hylton <jhylton@users.sourceforge.net>
 .. sectionauthor:: Moshe Zadka <moshez@users.sourceforge.net>
 
 
-
-
 The :mod:`urllib2` module defines functions and classes which help in opening
 URLs (mostly HTTP) in a complex world --- basic and digest authentication,
 redirections, cookies and more.

Doc-3k/library/urlparse.rst

-
 :mod:`urlparse` --- Parse URLs into components
 ==============================================
 
 .. module:: urlparse
-
-
+   :synopsis: Parse URLs into or assemble them from components.
 
 
 .. index::

Doc-3k/library/wsgiref.rst

-
 :mod:`wsgiref` --- WSGI Utilities and Reference Implementation
 ==============================================================
 
 .. module:: wsgiref
-   :synopsis: WSGI Utilities and Reference Implementation
+   :synopsis: WSGI Utilities and Reference Implementation.
 .. moduleauthor:: Phillip J. Eby <pje@telecommunity.com>
 .. sectionauthor:: Phillip J. Eby <pje@telecommunity.com>
 
 -------------------------------------------------
 
 .. module:: wsgiref.util
+   :synopsis: WSGI environment utilities.
 
 
 This module provides a variety of utility functions for working with WSGI
 ----------------------------------------------------
 
 .. module:: wsgiref.headers
+   :synopsis: WSGI response header tools.
 
 
 This module provides a single class, :class:`Headers`, for convenient
 ---------------------------------------------------------
 
 .. module:: wsgiref.simple_server
+   :synopsis: A simple WSGI HTTP server.
 
 
 This module implements a simple HTTP server (based on :mod:`BaseHTTPServer`)
 :mod:`wsgiref.util`.)
 
 
-.. function:: make_server(host, port, app [, server_class=:class:`WSGIServer` [, handler_class=:class:`WSGIRequestHandler`]])
+.. function:: make_server(host, port, app [, server_class=WSGIServer [, handler_class=:class:`WSGIRequestHandler`]])
 
    Create a new WSGI server listening on *host* and *port*, accepting connections
    for *app*.  The return value is an instance of the supplied *server_class*, and
       interface.
 
 
-:mod:`wsgiref.validate` -- WSGI conformance checker
----------------------------------------------------
+:mod:`wsgiref.validate` --- WSGI conformance checker
+----------------------------------------------------
 
 .. module:: wsgiref.validate
+   :synopsis: WSGI conformance checker.
 
 
 When creating new WSGI application objects, frameworks, servers, or middleware,
 ------------------------------------------------------
 
 .. module:: wsgiref.handlers
+   :synopsis: WSGI server/gateway base classes.
 
 
 This module provides base handler classes for implementing WSGI servers and
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.