Commits

Anonymous committed 17ca679

Add missing synopses for library modules.

  • Participants
  • Parent commits 7ef507b

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

File 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.
 

File Doc-26/library/code.rst

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

File 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>
 

File 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:

File 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

File 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.
 

File 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

File 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>

File Doc-26/library/mailcap.rst

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

File 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>
 

File 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

File Doc-26/library/os.path.rst

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

File 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[, ...]])

File 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>

File Doc-26/library/re.rst

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

File 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

File 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>

File Doc-26/library/struct.rst

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

File 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.

File Doc-26/library/urlparse.rst

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

File 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

File 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.
 

File Doc-3k/library/code.rst

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

File 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>
 

File 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:

File 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

File 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.
 

File 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

File 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>

File Doc-3k/library/mailcap.rst

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

File 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

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

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

File 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[, ...]])

File 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>

File Doc-3k/library/re.rst

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

File 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

File 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>

File Doc-3k/library/struct.rst

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

File 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.

File Doc-3k/library/urlparse.rst

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

File 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