Docstring fixes for enginefacade

There were some issues with the docstrings, and there are
probably still issues that I didn't get around to fixing.

Change-Id: I84d60621246776f77f9022f0f1d61792edccbfb0

1 files changed, 58 insertions, 61 deletions

diff --git a/oslo_db/sqlalchemy/enginefacade.py b/oslo_db/sqlalchemy/enginefacade.py
index 9243351..0985ea8 100644
--- a/oslo_db/sqlalchemy/enginefacade.py
+++ b/oslo_db/sqlalchemy/enginefacade.py
@@ -183,12 +183,12 @@ class _TransactionFactory(object):
 
         The configurational options given here act as **defaults**
         when the :class:`._TransactionFactory` is configured using
-        a :class:`.oslo.config.cfg.ConfigOpts` object; the options
-        present within the :class:`.oslo.config.cfg.ConfigOpts` **take
+        a :class:`oslo_config.cfg.ConfigOpts` object; the options
+        present within the :class:`oslo_config.cfg.ConfigOpts` **take
         precedence** versus the arguments passed here.  By default,
         the :class:`._TransactionFactory` loads in the configuration from
-        :data:`oslo.config.cfg.CONF`, after applying the
-        :data:`oslo.db.options.database_opts` configurational defaults to it.
+        :data:`oslo_config.cfg.CONF`, after applying the
+        :data:`oslo_db.options.database_opts` configurational defaults to it.
 
         .. seealso::
 
@@ -206,7 +206,7 @@ class _TransactionFactory(object):
         Behavior here is the same as that of
         :meth:`._TransactionFactory.configure_defaults`,
         with the exception that values specified here will **supersede** those
-        setup in the :class:`.oslo.config.cfg.ConfigOpts` options.
+        setup in the :class:`oslo_config.cfg.ConfigOpts` options.
 
         .. seealso::
 
@@ -841,9 +841,8 @@ writer = _context_manager.writer
 class LegacyEngineFacade(object):
     """A helper class for removing of global engine instances from oslo.db.
 
-    .. deprecated::
-        EngineFacade is deprecated.  Please use
-        oslo.db.sqlalchemy.enginefacade for new development.
+    .. deprecated:: 1.12.0
+        Please use :mod:`oslo_db.sqlalchemy.enginefacade` for new development.
 
     As a library, oslo.db can't decide where to store/when to create engine
     and sessionmaker instances, so this must be left for a target application.
@@ -866,64 +865,62 @@ class LegacyEngineFacade(object):
        transactional context (i.e. it's not thread-safe). sessionmaker is
        a factory of sessions.
 
+    :param sql_connection: the connection string for the database to use
+    :type sql_connection: string
+
+    :param slave_connection: the connection string for the 'slave' database
+                             to use. If not provided, the master database
+                             will be used for all operations. Note: this
+                             is meant to be used for offloading of read
+                             operations to asynchronously replicated slaves
+                             to reduce the load on the master database.
+    :type slave_connection: string
+
+    :param sqlite_fk: enable foreign keys in SQLite
+    :type sqlite_fk: bool
+
+    :param autocommit: use autocommit mode for created Session instances
+    :type autocommit: bool
+
+    :param expire_on_commit: expire session objects on commit
+    :type expire_on_commit: bool
+
+    Keyword arguments:
+
+    :keyword mysql_sql_mode: the SQL mode to be used for MySQL sessions.
+                             (defaults to TRADITIONAL)
+    :keyword idle_timeout: timeout before idle sql connections are reaped
+                           (defaults to 3600)
+    :keyword connection_debug: verbosity of SQL debugging information.
+                               -1=Off, 0=None, 100=Everything (defaults
+                               to 0)
+    :keyword max_pool_size: maximum number of SQL connections to keep open
+                            in a pool (defaults to SQLAlchemy settings)
+    :keyword max_overflow: if set, use this value for max_overflow with
+                           sqlalchemy (defaults to SQLAlchemy settings)
+    :keyword pool_timeout: if set, use this value for pool_timeout with
+                           sqlalchemy (defaults to SQLAlchemy settings)
+    :keyword sqlite_synchronous: if True, SQLite uses synchronous mode
+                                 (defaults to True)
+    :keyword connection_trace: add python stack traces to SQL as comment
+                               strings (defaults to False)
+    :keyword max_retries: maximum db connection retries during startup.
+                          (setting -1 implies an infinite retry count)
+                          (defaults to 10)
+    :keyword retry_interval: interval between retries of opening a sql
+                             connection (defaults to 10)
+    :keyword thread_checkin: boolean that indicates that between each
+                             engine checkin event a sleep(0) will occur to
+                             allow other greenthreads to run (defaults to
+                             True)
+
     """
     def __init__(self, sql_connection, slave_connection=None,
                  sqlite_fk=False, autocommit=True,
                  expire_on_commit=False, _conf=None, _factory=None, **kwargs):
-        """Initialize engine and sessionmaker instances.
-
-        :param sql_connection: the connection string for the database to use
-        :type sql_connection: string
-
-        :param slave_connection: the connection string for the 'slave' database
-                                 to use. If not provided, the master database
-                                 will be used for all operations. Note: this
-                                 is meant to be used for offloading of read
-                                 operations to asynchronously replicated slaves
-                                 to reduce the load on the master database.
-        :type slave_connection: string
-
-        :param sqlite_fk: enable foreign keys in SQLite
-        :type sqlite_fk: bool
-
-        :param autocommit: use autocommit mode for created Session instances
-        :type autocommit: bool
-
-        :param expire_on_commit: expire session objects on commit
-        :type expire_on_commit: bool
-
-        Keyword arguments:
-
-        :keyword mysql_sql_mode: the SQL mode to be used for MySQL sessions.
-                                 (defaults to TRADITIONAL)
-        :keyword idle_timeout: timeout before idle sql connections are reaped
-                               (defaults to 3600)
-        :keyword connection_debug: verbosity of SQL debugging information.
-                                   -1=Off, 0=None, 100=Everything (defaults
-                                   to 0)
-        :keyword max_pool_size: maximum number of SQL connections to keep open
-                                in a pool (defaults to SQLAlchemy settings)
-        :keyword max_overflow: if set, use this value for max_overflow with
-                               sqlalchemy (defaults to SQLAlchemy settings)
-        :keyword pool_timeout: if set, use this value for pool_timeout with
-                               sqlalchemy (defaults to SQLAlchemy settings)
-        :keyword sqlite_synchronous: if True, SQLite uses synchronous mode
-                                     (defaults to True)
-        :keyword connection_trace: add python stack traces to SQL as comment
-                                   strings (defaults to False)
-        :keyword max_retries: maximum db connection retries during startup.
-                              (setting -1 implies an infinite retry count)
-                              (defaults to 10)
-        :keyword retry_interval: interval between retries of opening a sql
-                                 connection (defaults to 10)
-        :keyword thread_checkin: boolean that indicates that between each
-                                 engine checkin event a sleep(0) will occur to
-                                 allow other greenthreads to run (defaults to
-                                 True)
-        """
         warnings.warn(
             "EngineFacade is deprecated; please use "
-            "oslo.db.sqlalchemy.enginefacade",
+            "oslo_db.sqlalchemy.enginefacade",
             exception.OsloDBDeprecationWarning,
             stacklevel=2)
 
@@ -997,7 +994,7 @@ class LegacyEngineFacade(object):
         """Initialize EngineFacade using oslo.config config instance options.
 
         :param conf: oslo.config config instance
-        :type conf: oslo.config.cfg.ConfigOpts
+        :type conf: oslo_config.cfg.ConfigOpts
 
         :param sqlite_fk: enable foreign keys in SQLite
         :type sqlite_fk: bool