Add missing synopses for library modules.

Doc-26/TODO

@@ -4,7 +4,6 @@ To do after conversion
 * 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

@@ -3,8 +3,7 @@
 ================================================
 
 .. module:: cgi
-
+   :synopsis: Helpers for running Python scripts via the Common Gateway Interface.
-
 
 
 .. index::
@@ -13,13 +12,10 @@
    pair: HTTP; protocol
    pair: MIME; headers
    single: URL
-
+   single: Common Gateway Interface
-.. index:: 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

@@ -3,7 +3,7 @@
 ========================================
 
 .. module:: code
-
+   :synopsis: Facilities to implement read-eval-print loops.
 
 
 

Doc-26/library/cookielib.rst

@@ -3,6 +3,7 @@
 =====================================================
 
 .. 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

@@ -1,16 +1,14 @@
-
 :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

@@ -1,7 +1,8 @@
 :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

@@ -1,14 +1,12 @@
-
 :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

@@ -1,18 +1,14 @@
-
+: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

@@ -1,8 +1,8 @@
-
 :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

@@ -1,9 +1,8 @@
-
+:mod:`mailcap` --- Mailcap file handling
-:mod:`mailcap` --- Mailcap file handling.
+========================================
-=========================================
 
 .. module:: mailcap
-
+   :synopsis: Mailcap file handling.
 
 
 

Doc-26/library/mimewriter.rst

@@ -1,9 +1,8 @@
-
 :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

@@ -1,13 +1,12 @@
-
+: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

@@ -3,8 +3,7 @@
 ================================================
 
 .. module:: os.path
-
+   :synopsis: Operations on pathnames.
-
 
 
 .. index:: single: path; operations

Doc-26/library/profile.rst

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

Doc-26/library/py_compile.rst

@@ -1,9 +1,8 @@
-
 :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

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

Doc-26/library/runpy.rst

@@ -1,15 +1,11 @@
-
+: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

@@ -1,9 +1,8 @@
-
 :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

@@ -3,9 +3,7 @@
 =========================================================
 
 .. module:: struct
-
+   :synopsis: Interpret strings as packed binary data.
-
-
 
 .. index::
    pair: C; structures

Doc-26/library/urllib2.rst

@@ -1,14 +1,12 @@
-
 :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

@@ -1,10 +1,8 @@
-
 :mod:`urlparse` --- Parse URLs into components
 ==============================================
 
 .. module:: urlparse
-
+   :synopsis: Parse URLs into or assemble them from components.
-
 
 
 .. index::

Doc-26/library/wsgiref.rst

@@ -1,9 +1,8 @@
-
 :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>
 
@@ -37,6 +36,7 @@ and other resources.
 -------------------------------------------------
 
 .. module:: wsgiref.util
+   :synopsis: WSGI environment utilities.
 
 
 This module provides a variety of utility functions for working with WSGI
@@ -142,6 +142,7 @@ also provides these miscellaneous utilities:
 ----------------------------------------------------
 
 .. module:: wsgiref.headers
+   :synopsis: WSGI response header tools.
 
 
 This module provides a single class, :class:`Headers`, for convenient
@@ -221,6 +222,7 @@ manipulation of WSGI response headers using a mapping-like interface.
 ---------------------------------------------------------
 
 .. module:: wsgiref.simple_server
+   :synopsis: A simple WSGI HTTP server.
 
 
 This module implements a simple HTTP server (based on :mod:`BaseHTTPServer`)
@@ -232,7 +234,7 @@ request.  (E.g., using the :func:`shift_path_info` function from
 :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
@@ -327,10 +329,11 @@ request.  (E.g., using the :func:`shift_path_info` function from
       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,
@@ -375,6 +378,7 @@ Paste" library.
 ------------------------------------------------------
 
 .. module:: wsgiref.handlers
+   :synopsis: WSGI server/gateway base classes.
 
 
 This module provides base handler classes for implementing WSGI servers and

Doc-3k/TODO

@@ -4,7 +4,6 @@ To do after conversion
 * 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

@@ -3,8 +3,7 @@
 ================================================
 
 .. module:: cgi
-
+   :synopsis: Helpers for running Python scripts via the Common Gateway Interface.
-
 
 
 .. index::
@@ -13,13 +12,10 @@
    pair: HTTP; protocol
    pair: MIME; headers
    single: URL
-
+   single: Common Gateway Interface
-.. index:: 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

@@ -3,7 +3,7 @@
 ========================================
 
 .. module:: code
-
+   :synopsis: Facilities to implement read-eval-print loops.
 
 
 

Doc-3k/library/cookielib.rst

@@ -3,6 +3,7 @@
 =====================================================
 
 .. 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

@@ -1,16 +1,14 @@
-
 :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

@@ -1,7 +1,8 @@
 :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

@@ -1,14 +1,12 @@
-
 :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

@@ -1,18 +1,14 @@
-
+: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

@@ -1,8 +1,8 @@
-
 :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

@@ -1,9 +1,8 @@
-
+:mod:`mailcap` --- Mailcap file handling
-:mod:`mailcap` --- Mailcap file handling.
+========================================
-=========================================
 
 .. module:: mailcap
-
+   :synopsis: Mailcap file handling.
 
 
 

Doc-3k/library/operator.rst

@@ -1,13 +1,12 @@
-
+: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

@@ -3,8 +3,7 @@
 ================================================
 
 .. module:: os.path
-
+   :synopsis: Operations on pathnames.
-
 
 
 .. index:: single: path; operations

Doc-3k/library/profile.rst

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

Doc-3k/library/py_compile.rst

@@ -1,9 +1,8 @@
-
 :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

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

Doc-3k/library/runpy.rst

@@ -1,15 +1,11 @@
-
+: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

@@ -1,9 +1,8 @@
-
 :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

@@ -3,9 +3,7 @@
 =========================================================
 
 .. module:: struct
-
+   :synopsis: Interpret strings as packed binary data.
-
-
 
 .. index::
    pair: C; structures

Doc-3k/library/urllib2.rst

@@ -1,14 +1,12 @@
-
 :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

@@ -1,10 +1,8 @@
-
 :mod:`urlparse` --- Parse URLs into components
 ==============================================
 
 .. module:: urlparse
-
+   :synopsis: Parse URLs into or assemble them from components.
-
 
 
 .. index::

Doc-3k/library/wsgiref.rst

@@ -1,9 +1,8 @@
-
 :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>
 
@@ -37,6 +36,7 @@ and other resources.
 -------------------------------------------------
 
 .. module:: wsgiref.util
+   :synopsis: WSGI environment utilities.
 
 
 This module provides a variety of utility functions for working with WSGI
@@ -142,6 +142,7 @@ also provides these miscellaneous utilities:
 ----------------------------------------------------
 
 .. module:: wsgiref.headers
+   :synopsis: WSGI response header tools.
 
 
 This module provides a single class, :class:`Headers`, for convenient
@@ -221,6 +222,7 @@ manipulation of WSGI response headers using a mapping-like interface.
 ---------------------------------------------------------
 
 .. module:: wsgiref.simple_server
+   :synopsis: A simple WSGI HTTP server.
 
 
 This module implements a simple HTTP server (based on :mod:`BaseHTTPServer`)
@@ -232,7 +234,7 @@ request.  (E.g., using the :func:`shift_path_info` function from
 :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
@@ -327,10 +329,11 @@ request.  (E.g., using the :func:`shift_path_info` function from
       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,
@@ -375,6 +378,7 @@ Paste" library.
 ------------------------------------------------------
 
 .. module:: wsgiref.handlers
+   :synopsis: WSGI server/gateway base classes.
 
 
 This module provides base handler classes for implementing WSGI servers and