Cross reference do_connect() event w/ creator

two questions today involving creator / do_connect,
do_connect is not well known enough, ensure docs are present
and prominent.

Change-Id: I85d518b9fc7b9b069a18010969abefa360134fe9

2 files changed, 16 insertions, 0 deletions

diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py
index dbe1e8b57..e683b6297 100644
--- a/lib/sqlalchemy/engine/create.py
+++ b/lib/sqlalchemy/engine/create.py
@@ -122,6 +122,18 @@ def create_engine(url, **kwargs):
         connections. Usage of this function causes connection
         parameters specified in the URL argument to be bypassed.
 
+        This hook is not as flexible as the newer
+        :class:`_events.DialectEvents.do_connect` hook which allows complete
+        control over how a connection is made to the database, given the full
+        set of URL arguments and state beforehand.
+
+        .. seealso::
+
+            :class:`_events.DialectEvents.do_connect` - event hook that allows
+            full control over DBAPI connection mechanics.
+
+            :ref:`custom_dbapi_args`
+
     :param echo=False: if True, the Engine will log all statements
         as well as a ``repr()`` of their parameter lists to the default log
         handler, which defaults to ``sys.stdout`` for output.   If set to the
diff --git a/lib/sqlalchemy/engine/events.py b/lib/sqlalchemy/engine/events.py
index 759f7f2bd..293c7afdd 100644
--- a/lib/sqlalchemy/engine/events.py
+++ b/lib/sqlalchemy/engine/events.py
@@ -758,6 +758,10 @@ class DialectEvents(event.Events):
 
         .. versionadded:: 1.0.3
 
+        .. seealso::
+
+            :ref:`custom_dbapi_args`
+
         """
 
     def do_executemany(self, cursor, statement, parameters, context):