merged mako doc generation branch

1 files changed, 24 insertions, 34 deletions

diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py
index c3651c88b..e72c37553 100644
--- a/lib/sqlalchemy/engine/__init__.py
+++ b/lib/sqlalchemy/engine/__init__.py
@@ -41,44 +41,30 @@ default_strategy = 'plain'
 def create_engine(*args, **kwargs):
     """Create a new Engine instance.
 
-    Using the given strategy name, locates that strategy and invokes
-    its create() method to produce the Engine.  The strategies
-    themselves are instances of EngineStrategy, and the built in ones
-    are present in the sqlalchemy.engine.strategies module.  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 DBAPI 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
-    connection and transaction without the need for explicit passing
-    of a Connection object.
-
     The standard method of specifying the engine is via URL as the
     first positional argument, to indicate the appropriate database
     dialect and connection arguments, with additional keyword
     arguments sent as options to the dialect and resulting Engine.
 
-    The URL is in the form ``<dialect>://opt1=val1&opt2=val2``, where
-    ``<dialect>`` is a name such as *mysql*, *oracle*, *postgres*, and the
-    options indicate username, password, database, etc.  Supported
-    keynames include `username`, `user`, `password`, `pw`, `db`,
-    `database`, `host`, `filename`.
+    The URL is in the form 
+    ``dialect://user:password@host/dbname[?key=value..]``, where 
+    ``dialect`` is a name such as ``mysql``, ``oracle``, ``postgres``,
+    etc.
 
     `**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
-      Defaults to None: an instance of ``sqlalchemy.pool.DBProxy`` or
+      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). If None, a default DBProxy will be created using the
-      engine's own database module with the given arguments.
+      section).  This argument supercedes "poolclass".
 
     echo
       Defaults to False: if True, the Engine will log all statements
@@ -102,21 +88,25 @@ def create_engine(*args, **kwargs):
       to all str types.
 
     module
-      Defaults to None: used by Oracle and Postgres, this is a
+      Defaults to None: this is a
       reference to a DBAPI2 module to be used instead of the engine's
       default module.  For Postgres, the default is psycopg2, or
       psycopg1 if 2 cannot be found.  For Oracle, its cx_Oracle.  For
       mysql, MySQLdb.
 
-    use_ansi
-      Defaults to True: used only by Oracle; when False, the Oracle
-      driver attempts to support a particular *quirk* of some Oracle
-      databases, that the ``LEFT OUTER JOIN`` SQL syntax is not
-      supported, and the *Oracle join* syntax of using
-      ``<column1>(+)=<column2>`` must be used in order to achieve a
-      ``LEFT OUTER JOIN``.  Its advised that the Oracle database be
-      configured to have full ANSI support instead of using this
-      feature.
+    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 DBAPI 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.
     """
 
     strategy = kwargs.pop('strategy', default_strategy)