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

1 files changed, 25 insertions, 30 deletions

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 = {}