fix most sphinx warnings (1.4)

still can't figure out the warnings with some of the older
changelog files.

this cherry-picks the sphinx fixes from 1.4 and additionally
fixes a small number of new issues in the 2.0 docs. However,
2.0 has many more errors to fix, primarily from the removal
of the legacy tutorials left behind a lot of labels that need
to be re-linked to the new tutorial.

Fixes: #7946
Change-Id: Id657ab23008eed0b133fed65b2f9ea75a626215c
(cherry picked from commit 9b55a423459236ca8a2ced713c9e93999dd18922)

1 files changed, 15 insertions, 9 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 80e458e7c..b2bdd6a8d 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -87,22 +87,22 @@ NO_OPTIONS: Mapping[str, Any] = util.EMPTY_DICT
 class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]):
     """Provides high-level functionality for a wrapped DB-API connection.
 
-    The :class:`_engine.Connection` object is procured by calling
-    the :meth:`_engine.Engine.connect` method of the :class:`_engine.Engine`
+    The :class:`_engine.Connection` object is procured by calling the
+    :meth:`_engine.Engine.connect` method of the :class:`_engine.Engine`
     object, and provides services for execution of SQL statements as well
     as transaction control.
 
-    The Connection object is **not** thread-safe.  While a Connection can be
+    The Connection object is **not** thread-safe. While a Connection can be
     shared among threads using properly synchronized access, it is still
     possible that the underlying DBAPI connection may not support shared
-    access between threads.  Check the DBAPI documentation for details.
+    access between threads. Check the DBAPI documentation for details.
 
     The Connection object represents a single DBAPI connection checked out
-    from the connection pool. In this state, the connection pool has no affect
-    upon the connection, including its expiration or timeout state. For the
-    connection pool to properly manage connections, connections should be
-    returned to the connection pool (i.e. ``connection.close()``) whenever the
-    connection is not in use.
+    from the connection pool. In this state, the connection pool has no
+    affect upon the connection, including its expiration or timeout state.
+    For the connection pool to properly manage connections, connections
+    should be returned to the connection pool (i.e. ``connection.close()``)
+    whenever the connection is not in use.
 
     .. index::
       single: thread safety; Connection
@@ -2631,6 +2631,12 @@ class Engine(
 
     @property
     def engine(self) -> Engine:
+        """Returns this :class:`.Engine`.
+
+        Used for legacy schemes that accept :class:`.Connection` /
+        :class:`.Engine` objects within the same variable.
+
+        """
         return self
 
     def clear_compiled_cache(self) -> None: