- merged -r5338:5429 of sphinx branch.

- Documentation has been converted to Sphinx.
In particular, the generated API documentation
has been constructed into a full blown
"API Reference" section which organizes
editorial documentation combined with
generated docstrings.   Cross linking between
sections and API docs are vastly improved,
a javascript-powered search feature is
provided, and a full index of all
classes, functions and members is provided.

5 files changed, 153 insertions, 107 deletions

diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py
index f22987976..6dde7a330 100644
--- a/lib/sqlalchemy/engine/__init__.py
+++ b/lib/sqlalchemy/engine/__init__.py
@@ -110,62 +110,112 @@ def create_engine(*args, **kwargs):
     ``dialect://user:password@host/dbname[?key=value..]``, where
     ``dialect`` is a name such as ``mysql``, ``oracle``, ``postgres``,
     etc.  Alternatively, the URL can be an instance of
-    ``sqlalchemy.engine.url.URL``.
-
-    `**kwargs` represents options to be sent to the Engine itself as
-    well as the components of the Engine, including the Dialect, the
-    ConnectionProvider, and the Pool.  A list of common options is as
-    follows:
-
-    poolclass
-      a subclass of ``sqlalchemy.pool.Pool`` which will be used to
-      instantiate a connection pool.
-
-    pool
-      an instance of ``sqlalchemy.pool.DBProxy`` or
-      ``sqlalchemy.pool.Pool`` to be used as the underlying source for
-      connections (DBProxy/Pool is described in the previous section).
-      This argument supercedes "poolclass".
-
-    echo
-      defaults to False: if True, the Engine will log all statements
-      as well as a repr() of their parameter lists to the engines
-      logger, which defaults to ``sys.stdout``.  A Engine instances'
-      `echo` data member can be modified at any time to turn logging
-      on and off.  If set to the string 'debug', result rows will be
-      printed to the standard output as well.
-
-    logger
-      defaults to None: a file-like object where logging output can be
-      sent, if `echo` is set to True.  This defaults to
-      ``sys.stdout``.
-
-    encoding
-      defaults to 'utf-8': the encoding to be used when
-      encoding/decoding Unicode strings.
-
-    convert_unicode
-      defaults to False: true if unicode conversion should be applied
-      to all str types.
-
-    module
-      defaults to None: this is a reference to a DB-API 2.0 module to
-      be used instead of the dialect's default module.
-
-    strategy
-      allows alternate Engine implementations to take effect.  Current
-      implementations include ``plain`` and ``threadlocal``.  The
-      default used by this function is ``plain``.
-
-      ``plain`` provides support for a Connection object which can be
-      used to execute SQL queries with a specific underlying DB-API
-      connection.
-
-      ``threadlocal`` is similar to ``plain`` except that it adds
-      support for a thread-local connection and transaction context,
-      which allows a group of engine operations to participate using
-      the same underlying connection and transaction without the need
-      for explicitly passing a single Connection.
+    :class:`~sqlalchemy.engine.url.URL`.
+
+    `**kwargs` takes a wide variety of options which are routed 
+    towards their appropriate components.  Arguments may be 
+    specific to the Engine, the underlying Dialect, as well as the 
+    Pool.  Specific dialects also accept keyword arguments that
+    are unique to that dialect.   Here, we describe the parameters
+    that are common to most ``create_engine()`` usage.
+    
+    :param assert_unicode=False: When set to ``True`` alongside
+        convert_unicode=``True``, asserts that incoming string bind
+        parameters are instances of ``unicode``, otherwise raises an
+        error. Only takes effect when ``convert_unicode==True``. This
+        flag is also available on the ``String`` type and its
+        descendants. New in 0.4.2.
+
+    :param connect_args: a dictionary of options which will be
+        passed directly to the DBAPI's ``connect()`` method as
+        additional keyword arguments.
+
+    :param convert_unicode=False: if set to True, all
+        String/character based types will convert Unicode values to raw
+        byte values going into the database, and all raw byte values to
+        Python Unicode coming out in result sets. This is an
+        engine-wide method to provide unicode conversion across the
+        board. For unicode conversion on a column-by-column level, use
+        the ``Unicode`` column type instead, described in `types`.
+
+    :param creator: a callable which returns a DBAPI connection.
+        This creation function will be passed to the underlying
+        connection pool and will be used to create all new database
+        connections. Usage of this function causes connection
+        parameters specified in the URL argument to be bypassed.
+
+    :param echo=False: if True, the Engine will log all statements
+        as well as a repr() of their parameter lists to the engines
+        logger, which defaults to sys.stdout. The ``echo`` attribute of
+        ``Engine`` can be modified at any time to turn logging on and
+        off. If set to the string ``"debug"``, result rows will be
+        printed to the standard output as well. This flag ultimately
+        controls a Python logger; see `dbengine_logging` at the end of
+        this chapter for information on how to configure logging
+        directly.
+
+    :param echo_pool=False: if True, the connection pool will log
+        all checkouts/checkins to the logging stream, which defaults to
+        sys.stdout. This flag ultimately controls a Python logger; see
+        `dbengine_logging` for information on how to configure logging
+        directly.
+
+    :param encoding='utf-8': the encoding to use for all Unicode
+        translations, both by engine-wide unicode conversion as well as
+        the ``Unicode`` type object.
+
+    :param label_length=None: optional integer value which limits
+        the size of dynamically generated column labels to that many
+        characters. If less than 6, labels are generated as
+        "_(counter)". If ``None``, the value of
+        ``dialect.max_identifier_length`` is used instead.
+
+    :param module=None: used by database implementations which
+        support multiple DBAPI modules, this is a reference to a DBAPI2
+        module to be used instead of the engine's default module. For
+        Postgres, the default is psycopg2. For Oracle, it's cx_Oracle.
+
+    :param pool=None: an already-constructed instance of
+        :class:`~sqlalchemy.pool.Pool`, such as a
+        :class:`~sqlalchemy.pool.QueuePool` instance. If non-None, this
+        pool will be used directly as the underlying connection pool
+        for the engine, bypassing whatever connection parameters are
+        present in the URL argument. For information on constructing
+        connection pools manually, see `pooling`.
+
+    :param poolclass=None: a :class:`~sqlalchemy.pool.Pool`
+        subclass, which will be used to create a connection pool
+        instance using the connection parameters given in the URL. Note
+        this differs from ``pool`` in that you don't actually
+        instantiate the pool in this case, you just indicate what type
+        of pool to be used.
+
+    :param max_overflow=10: the number of connections to allow in
+        connection pool "overflow", that is connections that can be
+        opened above and beyond the pool_size setting, which defaults
+        to five. this is only used with :class:`~sqlalchemy.pool.QueuePool`.
+
+    :param pool_size=5: the number of connections to keep open
+        inside the connection pool. This used with :class:`~sqlalchemy.pool.QueuePool` as
+        well as :class:`~sqlalchemy.pool.SingletonThreadPool`.
+
+    :param pool_recycle=-1: this setting causes the pool to recycle
+        connections after the given number of seconds has passed. It
+        defaults to -1, or no timeout. For example, setting to 3600
+        means connections will be recycled after one hour. Note that
+        MySQL in particular will ``disconnect automatically`` if no
+        activity is detected on a connection for eight hours (although
+        this is configurable with the MySQLDB connection itself and the
+        server configuration as well).
+
+    :param pool_timeout=30: number of seconds to wait before giving
+        up on getting a connection from the pool. This is only used
+        with :class:`~sqlalchemy.pool.QueuePool`.
+
+    :param strategy='plain': used to invoke alternate :class:`~sqlalchemy.engine.base.Engine.`
+        implementations. Currently available is the ``threadlocal``
+        strategy, which is described in :ref:`threadlocal_strategy`.
+    
     """
 
     strategy = kwargs.pop('strategy', default_strategy)
diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index d22e21cfe..97624280e 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -47,22 +47,22 @@ class Dialect(object):
       'utf-8'.
 
     schemagenerator
-      a [sqlalchemy.schema#SchemaVisitor] class which generates
+      a :class:`~sqlalchemy.schema.SchemaVisitor` class which generates
       schemas.
 
     schemadropper
-      a [sqlalchemy.schema#SchemaVisitor] class which drops schemas.
+      a :class:`~sqlalchemy.schema.SchemaVisitor` class which drops schemas.
 
     defaultrunner
-      a [sqlalchemy.schema#SchemaVisitor] class which executes
+      a :class:`~sqlalchemy.schema.SchemaVisitor` class which executes
       defaults.
 
     statement_compiler
-      a [sqlalchemy.engine.base#Compiled] class used to compile SQL
+      a :class:`~sqlalchemy.engine.base.Compiled` class used to compile SQL
       statements
 
     preparer
-      a [sqlalchemy.sql.compiler#IdentifierPreparer] class used to
+      a :class:`~sqlalchemy.sql.compiler.IdentifierPreparer` class used to
       quote identifiers.
 
     supports_alter
@@ -107,7 +107,7 @@ class Dialect(object):
     def create_connect_args(self, url):
         """Build DB-API compatible connection arguments.
 
-        Given a [sqlalchemy.engine.url#URL] object, returns a tuple
+        Given a :class:`~sqlalchemy.engine.url.URL` object, returns a tuple
         consisting of a `*args`/`**kwargs` suitable to send directly
         to the dbapi's connect function.
         """
@@ -118,11 +118,11 @@ class Dialect(object):
     def type_descriptor(self, typeobj):
         """Transform a generic type to a database-specific type.
 
-        Transforms the given [sqlalchemy.types#TypeEngine] instance
+        Transforms the given :class:`~sqlalchemy.types.TypeEngine` instance
         from generic to database-specific.
 
         Subclasses will usually use the
-        [sqlalchemy.types#adapt_type()] method in the types module to
+        :func:`~sqlalchemy.types.adapt_type` method in the types module to
         make this job easy.
         """
 
@@ -137,8 +137,8 @@ class Dialect(object):
     def reflecttable(self, connection, table, include_columns=None):
         """Load table description from the database.
 
-        Given a [sqlalchemy.engine#Connection] and a
-        [sqlalchemy.schema#Table] object, reflect its columns and
+        Given a :class:`~sqlalchemy.engine.Connection` and a
+        :class:`~sqlalchemy.schema.Table` object, reflect its columns and
         properties from the database.  If include_columns (a list or
         set) is specified, limit the autoload to the given column
         names.
@@ -149,7 +149,7 @@ class Dialect(object):
     def has_table(self, connection, table_name, schema=None):
         """Check the existence of a particular table in the database.
 
-        Given a [sqlalchemy.engine#Connection] object and a string
+        Given a :class:`~sqlalchemy.engine.Connection` object and a string
         `table_name`, return True if the given table (possibly within
         the specified `schema`) exists in the database, False
         otherwise.
@@ -160,7 +160,7 @@ class Dialect(object):
     def has_sequence(self, connection, sequence_name, schema=None):
         """Check the existence of a particular sequence in the database.
 
-        Given a [sqlalchemy.engine#Connection] object and a string
+        Given a :class:`~sqlalchemy.engine.Connection` object and a string
         `sequence_name`, return True if the given sequence exists in
         the database, False otherwise.
         """
@@ -168,12 +168,12 @@ class Dialect(object):
         raise NotImplementedError()
 
     def get_default_schema_name(self, connection):
-        """Return the string name of the currently selected schema given a [sqlalchemy.engine#Connection]."""
+        """Return the string name of the currently selected schema given a :class:`~sqlalchemy.engine.Connection`."""
 
         raise NotImplementedError()
 
     def create_execution_context(self, connection, compiled=None, compiled_parameters=None, statement=None, parameters=None):
-        """Return a new [sqlalchemy.engine#ExecutionContext] object."""
+        """Return a new :class:`~sqlalchemy.engine.ExecutionContext` object."""
 
         raise NotImplementedError()
 
@@ -506,7 +506,7 @@ class Connection(Connectable):
         """Construct a new Connection.
 
         Connection objects are typically constructed by an
-        [sqlalchemy.engine#Engine], see the ``connect()`` and
+        :class:`~sqlalchemy.engine.Engine`, see the ``connect()`` and
         ``contextual_connect()`` methods of Engine.
         
         """
@@ -630,7 +630,7 @@ class Connection(Connectable):
         This method can be used to insulate the rest of an application
         from a modified state on a connection (such as a transaction
         isolation level or similar).  Also see
-        [sqlalchemy.interfaces#PoolListener] for a mechanism to modify
+        :class:`~sqlalchemy.interfaces.PoolListener` for a mechanism to modify
         connection state when connections leave and return to their
         connection pool.
 
@@ -1064,8 +1064,9 @@ class TwoPhaseTransaction(Transaction):
 
 class Engine(Connectable):
     """
-    Connects a Pool, a Dialect and a CompilerFactory together to
-    provide a default implementation of SchemaEngine.
+    Connects a :class:`~sqlalchemy.pool.Pool` and :class:`~sqlalchemy.engine.base.Dialect` 
+    together to provide a source of database connectivity and behavior.
+
     """
 
     def __init__(self, pool, dialect, url, echo=None, proxy=None):
@@ -1082,7 +1083,7 @@ class Engine(Connectable):
 
     @property
     def name(self):
-        "String name of the [sqlalchemy.engine#Dialect] in use by this ``Engine``."
+        "String name of the :class:`~sqlalchemy.engine.Dialect` in use by this ``Engine``."
         
         return self.dialect.name
 
diff --git a/lib/sqlalchemy/engine/strategies.py b/lib/sqlalchemy/engine/strategies.py
index 62a4b9bb8..fa608df65 100644
--- a/lib/sqlalchemy/engine/strategies.py
+++ b/lib/sqlalchemy/engine/strategies.py
@@ -2,7 +2,7 @@
 
 These are semi-private implementation classes which provide the
 underlying behavior for the "strategy" keyword argument available on
-[sqlalchemy.engine#create_engine()].  Current available options are
+:func:`~sqlalchemy.engine.create_engine`.  Current available options are
 ``plain``, ``threadlocal``, and ``mock``.
 
 New strategies can be added via new ``EngineStrategy`` classes.
diff --git a/lib/sqlalchemy/engine/threadlocal.py b/lib/sqlalchemy/engine/threadlocal.py
index e0dae8de3..23c9cd0c1 100644
--- a/lib/sqlalchemy/engine/threadlocal.py
+++ b/lib/sqlalchemy/engine/threadlocal.py
@@ -1,7 +1,7 @@
 """Provides a thread-local transactional wrapper around the root Engine class.
 
 The ``threadlocal`` module is invoked when using the ``strategy="threadlocal"`` flag
-with [sqlalchemy.engine#create_engine()].  This module is semi-private and is 
+with :func:`~sqlalchemy.engine.create_engine`.  This module is semi-private and is 
 invoked automatically when the threadlocal engine strategy is used.
 """
 
diff --git a/lib/sqlalchemy/engine/url.py b/lib/sqlalchemy/engine/url.py
index b81a91d59..e00efd6c0 100644
--- a/lib/sqlalchemy/engine/url.py
+++ b/lib/sqlalchemy/engine/url.py
@@ -1,7 +1,7 @@
-"""Provides the [sqlalchemy.engine.url#URL] class which encapsulates
+"""Provides the :class:`~sqlalchemy.engine.url.URL` class which encapsulates
 information about a database connection specification.
 
-The URL object is created automatically when [sqlalchemy.engine#create_engine()] is called
+The URL object is created automatically when :func:`~sqlalchemy.engine.create_engine` is called
 with a string argument; alternatively, the URL is a public-facing construct which can
 be used directly and is also accepted directly by ``create_engine()``.
 """
@@ -18,30 +18,25 @@ class URL(object):
     string by the ``module-level make_url()`` function.  the string
     format of the URL is an RFC-1738-style string.
 
-    Attributes on URL include:
-
-    drivername
-      the name of the database backend.  This name will correspond to
-      a module in sqlalchemy/databases or a third party plug-in.
+    All initialization parameters are available as public attributes.
+    
+    :param drivername: the name of the database backend.  
+        This name will correspond to a module in sqlalchemy/databases 
+        or a third party plug-in.
 
-    username
-      The user name for the connection.
+    :param username: The user name.
 
-    password
-      database password.
+    :param password: database password.
 
-    host
-      The name of the host.
+    :param host: The name of the host.
 
-    port
-      The port number.
+    :param port: The port number.
 
-    database
-      The database.
+    :param database: The database name.
 
-    query
-      A dictionary containing key/value pairs representing the URL's
-      query string.
+    :param query: A dictionary of options to be passed to the 
+        dialect and/or the DBAPI upon connect.
+        
     """
 
     def __init__(self, drivername, username=None, password=None, host=None, port=None, database=None, query=None):
@@ -107,18 +102,18 @@ class URL(object):
         used as the keys by default.  Unset or false attributes are omitted
         from the final dictionary.
 
-        \**kw
-          Optional, alternate key names for url attributes::
+        :param \**kw: Optional, alternate key names for url 
+            attributes::
 
-            # return 'username' as 'user'
-            username='user'
+                # return 'username' as 'user'
+                username='user'
 
-            # omit 'database'
-            database=None
-          
-        names
-          Deprecated.  A list of key names. Equivalent to the keyword
-          usage, must be provided in the order above.
+                # omit 'database'
+                database=None
+        
+        :param names: Deprecated.  Same purpose as the keyword-based alternate names,
+            but correlates the name to the original positionally.
+        
         """
 
         translated = {}