Fix almost all read-level sphinx warnings

There are some related to changelog that I can't figure out
and are likely due to something in the changelog extension.
also one thing with a "collection" I can't figure out.

Change-Id: I0a9e6f4291c3589aa19a4abcb9245cd22a266fe0

8 files changed, 22 insertions, 11 deletions

diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py
index 7f0270b42..db5f9dee7 100644
--- a/lib/sqlalchemy/engine/__init__.py
+++ b/lib/sqlalchemy/engine/__init__.py
@@ -33,6 +33,7 @@ from .interfaces import ExceptionContext  # noqa
 from .interfaces import ExecutionContext  # noqa
 from .interfaces import TypeCompiler  # noqa
 from .mock import create_mock_engine
+from .result import BaseResult  # noqa
 from .result import BaseRow  # noqa
 from .result import BufferedColumnResultProxy  # noqa
 from .result import BufferedColumnRow  # noqa
diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index d08b35a2e..029a28c68 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -98,7 +98,9 @@ relationship = public_factory(RelationshipProperty, ".orm.relationship")
 
 @_sa_util.deprecated_20("relation", "Please use :func:`.relationship`.")
 def relation(*arg, **kw):
-    """A synonym for :func:`relationship`."""
+    """A synonym for :func:`relationship`.
+
+    """
 
     return relationship(*arg, **kw)
 
diff --git a/lib/sqlalchemy/sql/base.py b/lib/sqlalchemy/sql/base.py
index eea4003f2..a02955c8c 100644
--- a/lib/sqlalchemy/sql/base.py
+++ b/lib/sqlalchemy/sql/base.py
@@ -578,7 +578,9 @@ class Executable(Generative):
         ":class:`.Session`.",
     )
     def execute(self, *multiparams, **params):
-        """Compile and execute this :class:`.Executable`."""
+        """Compile and execute this :class:`.Executable`.
+
+        """
         e = self.bind
         if e is None:
             label = getattr(self, "description", self.__class__.__name__)
diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index 4dc2b8bbf..e25063372 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -19,6 +19,7 @@ __all__ = [
     "AliasedReturnsRows",
     "any_",
     "all_",
+    "CacheKey",
     "ClauseElement",
     "ColumnCollection",
     "ColumnElement",
@@ -159,6 +160,7 @@ from .selectable import TableSample  # noqa
 from .selectable import TextAsFrom  # noqa
 from .selectable import TextualSelect  # noqa
 from .selectable import Values  # noqa
+from .traversals import CacheKey  # noqa
 from .visitors import Visitable  # noqa
 from ..util.langhelpers import public_factory  # noqa
 
diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index 56695708e..d65821c5c 100644
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -787,7 +787,9 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
         ":meth:`.Inspector.has_table`.",
     )
     def exists(self, bind=None):
-        """Return True if this table exists."""
+        """Return True if this table exists.
+
+        """
 
         if bind is None:
             bind = _bind_or_error(self)
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index 595b1bdfa..9c593ea5d 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -3814,19 +3814,19 @@ class Select(
         "1.4",
         "The :meth:`.Select.column` method is deprecated and will "
         "be removed in a future release.  Please use "
-        ":meth:`.Select.add_columns",
+        ":meth:`.Select.add_columns`",
     )
     def column(self, column):
         """return a new select() construct with the given column expression
-            added to its columns clause.
+           added to its columns clause.
 
-            E.g.::
+           E.g.::
 
                 my_select = my_select.column(table.c.new_column)
 
-            See the documentation for :meth:`.Select.with_only_columns`
-            for guidelines on adding /replacing the columns of a
-            :class:`.Select` object.
+           See the documentation for :meth:`.Select.with_only_columns`
+           for guidelines on adding /replacing the columns of a
+           :class:`.Select` object.
 
         """
         return self.add_columns(column)
diff --git a/lib/sqlalchemy/sql/visitors.py b/lib/sqlalchemy/sql/visitors.py
index 5504bf3d8..29ed01309 100644
--- a/lib/sqlalchemy/sql/visitors.py
+++ b/lib/sqlalchemy/sql/visitors.py
@@ -386,7 +386,7 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)):
     """visit the values() ordered tuple list of an :class:`.Update` object."""
 
     dp_dml_values = symbol("DML_V")
-    """visit the values() dictionary of a :class:`.ValuesBase
+    """visit the values() dictionary of a :class:`.ValuesBase`
     (e.g. Insert or Update) object.
 
     """
diff --git a/lib/sqlalchemy/util/langhelpers.py b/lib/sqlalchemy/util/langhelpers.py
index 7e9906028..bd670f2cc 100644
--- a/lib/sqlalchemy/util/langhelpers.py
+++ b/lib/sqlalchemy/util/langhelpers.py
@@ -223,7 +223,7 @@ def %(name)s(%(args)s):
             "Inherited from :func:`sqlalchemy%s`; this constructor "
             "creates a :class:`%s` object"
             % (linked_to_location, class_location),
-            0,
+            1,
         )
         decorated.__doc__ = linked_to_doc
     else:
@@ -1637,6 +1637,8 @@ def _dedent_docstring(text):
 def inject_docstring_text(doctext, injecttext, pos):
     doctext = _dedent_docstring(doctext or "")
     lines = doctext.split("\n")
+    if len(lines) == 1:
+        lines.append("")
     injectlines = textwrap.dedent(injecttext).split("\n")
     if injectlines[0]:
         injectlines.insert(0, "")