Add a lot more detail

(cherry picked from commit 5db5e18d3babdb3ee857c075c774a585505b78ce)

diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py
index 4b6e752ba76de492a8ccbaa3b991cab5d87f461e..0b0d50329aeea318e1511ef5caebcafcdcdf8185 100644 (file)
--- a/lib/sqlalchemy/engine/__init__.py
+++ b/lib/sqlalchemy/engine/__init__.py
@@ -389,14 +389,33 @@ def create_engine(*args, **kwargs):
 def engine_from_config(configuration, prefix='sqlalchemy.', **kwargs):
     """Create a new Engine instance using a configuration dictionary.
 
-    The *configuration* dictionary is typically produced from a config file
-    in which keys are prefixed, e.g. ``sqlalchemy.url``, ``sqlalchemy.echo``,
-    etc.  The 'prefix' argument indicates the prefix to be searched for.
+    The dictionary is typically produced from a config file.
+    
+    The keys of interest to ``engine_from_config()`` should be prefixed, e.g.
+    ``sqlalchemy.url``, ``sqlalchemy.echo``, etc.  The 'prefix' argument
+    indicates the prefix to be searched for.  Each matching key (after the
+    prefix is stripped) is treated as though it were the corresponding keyword
+    argument to a :func:`.create_engine` call.
+
+    The only required key is (assuming the default prefix) ``sqlalchemy.url``,
+    which provides the :ref:`database URL <database_urls>`.
 
     A select set of keyword arguments will be "coerced" to their
     expected type based on string values.    The set of arguments
     is extensible per-dialect using the ``engine_config_types`` accessor.
 
+    :param configuration: A dictionary (typically produced from a config file,
+        but this is not a requirement).  Items whose keys start with the value
+        of 'prefix' will have that prefix stripped, and will then be passed to
+        :ref:`create_engine`.
+
+    :param prefix: Prefix to match and then strip from keys
+        in 'configuration'.
+
+    :param kwargs: Each keyword argument to ``engine_from_config()`` itself
+        overrides the corresponding item taken from the 'configuration'
+        dictionary.  Keyword arguments should *not* be prefixed.
+
     """
 
     options = dict((key[len(prefix):], configuration[key])