Fix a wide variety of typos and broken links

Note the PR has a few remaining doc linking issues
listed in the comment that must be addressed separately.

Signed-off-by: aplatkouski <5857672+aplatkouski@users.noreply.github.com>
Closes: #5371
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/5371
Pull-request-sha: 7e7d233cf3a0c66980c27db0fcdb3c7d93bc2510

Change-Id: I9c36e8d8804483950db4b42c38ee456e384c59e3

13 files changed, 296 insertions, 279 deletions

diff --git a/lib/sqlalchemy/sql/base.py b/lib/sqlalchemy/sql/base.py
index 4c603b6dd..9dcd7dca9 100644
--- a/lib/sqlalchemy/sql/base.py
+++ b/lib/sqlalchemy/sql/base.py
@@ -617,7 +617,7 @@ class CacheableOptions(Options, HasCacheKey):
 
 
 class Executable(Generative):
-    """Mark a ClauseElement as supporting execution.
+    """Mark a :class:`_expression.ClauseElement` as supporting execution.
 
     :class:`.Executable` is a superclass for all "statement" types
     of objects, including :func:`select`, :func:`delete`, :func:`update`,
@@ -880,7 +880,7 @@ class ColumnCollection(object):
         Column('x', Integer(), table=None)
         >>> cc['y']
 
-    :class`.ColumnCollection` also indexes the columns in order and allows
+    :class:`.ColumnCollection` also indexes the columns in order and allows
     them to be accessible by their integer position::
 
         >>> cc[0]
@@ -898,8 +898,8 @@ class ColumnCollection(object):
         [Column('x', Integer(), table=None),
          Column('y', Integer(), table=None)]
 
-    The base :class:`_expression.ColumnCollection` object can store duplicates
-    , which can
+    The base :class:`_expression.ColumnCollection` object can store
+    duplicates, which can
     mean either two columns with the same key, in which case the column
     returned by key  access is **arbitrary**::
 
@@ -1079,23 +1079,23 @@ class ColumnCollection(object):
         ancestor column.
 
         :param column: the target :class:`_expression.ColumnElement`
-                      to be matched
+                      to be matched.
 
         :param require_embedded: only return corresponding columns for
          the given :class:`_expression.ColumnElement`, if the given
          :class:`_expression.ColumnElement`
          is actually present within a sub-element
-         of this :class:`expression.Selectable`.
+         of this :class:`_expression.Selectable`.
          Normally the column will match if
          it merely shares a common ancestor with one of the exported
-         columns of this :class:`expression.Selectable`.
+         columns of this :class:`_expression.Selectable`.
 
         .. seealso::
 
-            :meth:`expression.Selectable.corresponding_column`
+            :meth:`_expression.Selectable.corresponding_column`
             - invokes this method
             against the collection returned by
-            :attr:`expression.Selectable.exported_columns`.
+            :attr:`_expression.Selectable.exported_columns`.
 
         .. versionchanged:: 1.4 the implementation for ``corresponding_column``
            was moved onto the :class:`_expression.ColumnCollection` itself.
diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py
index b5e85ffb8..89b561674 100644
--- a/lib/sqlalchemy/sql/compiler.py
+++ b/lib/sqlalchemy/sql/compiler.py
@@ -2569,8 +2569,8 @@ class SQLCompiler(Compiled):
         return froms
 
     translate_select_structure = None
-    """if none None, should be a callable which accepts (select_stmt, **kw)
-    and returns a select object.   this is used for structural changes
+    """if not ``None``, should be a callable which accepts ``(select_stmt,
+    **kw)`` and returns a select object.   this is used for structural changes
     mostly to accommodate for LIMIT/OFFSET schemes
 
     """
diff --git a/lib/sqlalchemy/sql/ddl.py b/lib/sqlalchemy/sql/ddl.py
index d3730b124..17e3be2da 100644
--- a/lib/sqlalchemy/sql/ddl.py
+++ b/lib/sqlalchemy/sql/ddl.py
@@ -93,10 +93,10 @@ class DDLElement(roles.DDLRole, Executable, _DDLCompiles):
           ``.bind`` property.
 
         :param target:
-          Optional, defaults to None.  The target SchemaItem for the
-          execute call.  Will be passed to the ``on`` callable if any,
-          and may also provide string expansion data for the
-          statement. See ``execute_at`` for more information.
+          Optional, defaults to None.  The target :class:`_schema.SchemaItem`
+          for the execute call.  Will be passed to the ``on`` callable if any,
+          and may also provide string expansion data for the statement.
+          See ``execute_at`` for more information.
 
         """
 
@@ -167,7 +167,7 @@ class DDLElement(roles.DDLRole, Executable, _DDLCompiles):
              set during the call to ``create()``, ``create_all()``,
              ``drop()``, ``drop_all()``.
 
-          If the callable returns a true value, the DDL statement will be
+          If the callable returns a True value, the DDL statement will be
           executed.
 
         :param state: any value which will be passed to the callable\_
@@ -955,8 +955,8 @@ class SchemaDropper(DDLBase):
 def sort_tables(
     tables, skip_fn=None, extra_dependencies=None,
 ):
-    """sort a collection of :class:`_schema.Table` objects based on dependency
-    .
+    """Sort a collection of :class:`_schema.Table` objects based on
+    dependency.
 
     This is a dependency-ordered sort which will emit :class:`_schema.Table`
     objects such that they will follow their dependent :class:`_schema.Table`
@@ -1040,7 +1040,7 @@ def sort_tables(
 def sort_tables_and_constraints(
     tables, filter_fn=None, extra_dependencies=None, _warn_for_cycles=False
 ):
-    """sort a collection of :class:`_schema.Table`  /
+    """Sort a collection of :class:`_schema.Table`  /
     :class:`_schema.ForeignKeyConstraint`
     objects.
 
diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py
index 50b2a935a..e5f856788 100644
--- a/lib/sqlalchemy/sql/dml.py
+++ b/lib/sqlalchemy/sql/dml.py
@@ -457,7 +457,7 @@ class ValuesBase(UpdateBase):
 
     @_generative
     def values(self, *args, **kwargs):
-        r"""specify a fixed VALUES clause for an INSERT statement, or the SET
+        r"""Specify a fixed VALUES clause for an INSERT statement, or the SET
         clause for an UPDATE.
 
         Note that the :class:`_expression.Insert` and
@@ -685,8 +685,8 @@ class ValuesBase(UpdateBase):
         added to any existing RETURNING clause, provided that
         :meth:`.UpdateBase.returning` is not used simultaneously.  The column
         values will then be available on the result using the
-        :attr:`_engine.CursorResult.returned_defaults` accessor as a dictionary
-        ,
+        :attr:`_engine.CursorResult.returned_defaults` accessor as
+        a dictionary,
         referring to values keyed to the :class:`_schema.Column`
         object as well as
         its ``.key``.
@@ -943,7 +943,7 @@ class DMLWhereBase(object):
 
     @_generative
     def where(self, whereclause):
-        """return a new construct with the given expression added to
+        """Return a new construct with the given expression added to
         its WHERE clause, joined to the existing clause via AND, if any.
 
         """
@@ -1122,7 +1122,7 @@ class Update(DMLWhereBase, ValuesBase):
           a scalar-returning :func:`_expression.select` construct,
           etc.
 
-        when combining :func:`_expression.select` constructs within the
+        When combining :func:`_expression.select` constructs within the
         values clause of an :func:`_expression.update`
         construct, the subquery represented
         by the :func:`_expression.select` should be *correlated* to the
diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 60c816ee6..402895dc7 100644
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -312,9 +312,11 @@ class ClauseElement(
             raise exc.ObjectNotExecutableError(self)
 
     def unique_params(self, *optionaldict, **kwargs):
-        """Return a copy with :func:`bindparam()` elements replaced.
+        """Return a copy with :func:`_expression.bindparam` elements
+        replaced.
 
-        Same functionality as ``params()``, except adds `unique=True`
+        Same functionality as :meth:`_expression.ClauseElement.params`,
+        except adds `unique=True`
         to affected bind parameters so that multiple statements can be
         used.
 
@@ -322,9 +324,11 @@ class ClauseElement(
         return self._replace_params(True, optionaldict, kwargs)
 
     def params(self, *optionaldict, **kwargs):
-        """Return a copy with :func:`bindparam()` elements replaced.
+        """Return a copy with :func:`_expression.bindparam` elements
+        replaced.
 
-        Returns a copy of this ClauseElement with :func:`bindparam()`
+        Returns a copy of this ClauseElement with
+        :func:`_expression.bindparam`
         elements replaced with values taken from the given dictionary::
 
           >>> clause = column('x') + bindparam('foo')
@@ -354,14 +358,15 @@ class ClauseElement(
         return cloned_traverse(self, {}, {"bindparam": visit_bindparam})
 
     def compare(self, other, **kw):
-        r"""Compare this ClauseElement to the given ClauseElement.
+        r"""Compare this :class:`_expression.ClauseElement` to
+        the given :class:`_expression.ClauseElement`.
 
         Subclasses should override the default behavior, which is a
         straight identity comparison.
 
-        \**kw are arguments consumed by subclass compare() methods and
-        may be used to modify the criteria for comparison.
-        (see :class:`_expression.ColumnElement`)
+        \**kw are arguments consumed by subclass ``compare()`` methods and
+        may be used to modify the criteria for comparison
+        (see :class:`_expression.ColumnElement`).
 
         """
         return traversals.compare(self, other, **kw)
@@ -396,8 +401,8 @@ class ClauseElement(
                     setattr(self, attrname, result)
 
     def get_children(self, omit_attrs=(), **kw):
-        r"""Return immediate child :class:`.Traversible` elements of this
-        :class:`.Traversible`.
+        r"""Return immediate child :class:`.visitors.Traversible`
+        elements of this :class:`.visitors.Traversible`.
 
         This is used for visit traversal.
 
@@ -732,12 +737,12 @@ class ColumnElement(
     """
 
     key = None
-    """the 'key' that in some circumstances refers to this object in a
+    """The 'key' that in some circumstances refers to this object in a
     Python namespace.
 
     This typically refers to the "key" of the column as present in the
-    ``.c`` collection of a selectable, e.g. sometable.c["somekey"] would
-    return a Column with a .key of "somekey".
+    ``.c`` collection of a selectable, e.g. ``sometable.c["somekey"]`` would
+    return a :class:`_schema.Column` with a ``.key`` of "somekey".
 
     """
 
@@ -970,7 +975,7 @@ class ColumnElement(
 
         This is a shortcut to the :func:`_expression.label` function.
 
-        if 'name' is None, an anonymous label name will be generated.
+        If 'name' is ``None``, an anonymous label name will be generated.
 
         """
         return Label(name, self, self.type)
@@ -989,14 +994,14 @@ class ColumnElement(
 
     @util.memoized_property
     def anon_label(self):
-        """provides a constant 'anonymous label' for this ColumnElement.
+        """Provides a constant 'anonymous label' for this ColumnElement.
 
         This is a label() expression which will be named at compile time.
-        The same label() is returned each time anon_label is called so
-        that expressions can reference anon_label multiple times, producing
-        the same label name at compile time.
+        The same label() is returned each time ``anon_label`` is called so
+        that expressions can reference ``anon_label`` multiple times,
+        producing the same label name at compile time.
 
-        the compiler uses this function automatically at compile time
+        The compiler uses this function automatically at compile time
         for expressions that are known to be 'unnamed' like binary
         expressions and function calls.
 
@@ -1689,7 +1694,7 @@ class TextClause(
         be eligible for autocommit if no transaction is in progress.
 
         :param text:
-          the text of the SQL statement to be created.  use ``:<param>``
+          the text of the SQL statement to be created.  Use ``:<param>``
           to specify bind parameters; they will be compiled to their
           engine-specific format.
 
@@ -1952,7 +1957,7 @@ class TextClause(
 
         :param \**types: A mapping of string names to :class:`.TypeEngine`
          type objects indicating the datatypes to use for names that are
-         SELECTed from the textual string.  Prefer to use the ``\*cols``
+         SELECTed from the textual string.  Prefer to use the ``*cols``
          argument as it also indicates positional ordering.
 
         """
@@ -2365,7 +2370,7 @@ class BooleanClauseList(ClauseList, ColumnElement):
 
     @classmethod
     def and_(cls, *clauses):
-        """Produce a conjunction of expressions joined by ``AND``.
+        r"""Produce a conjunction of expressions joined by ``AND``.
 
         E.g.::
 
@@ -2395,8 +2400,8 @@ class BooleanClauseList(ClauseList, ColumnElement):
         clause being combined using :func:`.and_`::
 
             stmt = select([users_table]).\
-                        where(users_table.c.name == 'wendy').\
-                        where(users_table.c.enrolled == True)
+                    where(users_table.c.name == 'wendy').\
+                    where(users_table.c.enrolled == True)
 
         The :func:`.and_` construct must be given at least one positional
         argument in order to be valid; a :func:`.and_` construct with no
@@ -2799,7 +2804,7 @@ def literal_column(text, type_=None):
     :param type\_: an optional :class:`~sqlalchemy.types.TypeEngine`
       object which will
       provide result-set translation and additional expression semantics for
-      this column. If left as None the type will be NullType.
+      this column. If left as ``None`` the type will be :class:`.NullType`.
 
     .. seealso::
 
@@ -3166,8 +3171,8 @@ class UnaryExpression(ColumnElement):
 
             from sqlalchemy import desc, nullsfirst
 
-            stmt = select([users_table]).\
-                        order_by(nullsfirst(desc(users_table.c.name)))
+            stmt = select([users_table]).order_by(
+                nullsfirst(desc(users_table.c.name)))
 
         The SQL expression from the above would resemble::
 
@@ -3179,9 +3184,8 @@ class UnaryExpression(ColumnElement):
         rather than as its standalone
         function version, as in::
 
-            stmt = (select([users_table]).
-                    order_by(users_table.c.name.desc().nullsfirst())
-                    )
+            stmt = select([users_table]).order_by(
+                users_table.c.name.desc().nullsfirst())
 
         .. seealso::
 
@@ -3211,8 +3215,8 @@ class UnaryExpression(ColumnElement):
 
             from sqlalchemy import desc, nullslast
 
-            stmt = select([users_table]).\
-                        order_by(nullslast(desc(users_table.c.name)))
+            stmt = select([users_table]).order_by(
+                nullslast(desc(users_table.c.name)))
 
         The SQL expression from the above would resemble::
 
@@ -3224,8 +3228,8 @@ class UnaryExpression(ColumnElement):
         rather than as its standalone
         function version, as in::
 
-            stmt = select([users_table]).\
-                        order_by(users_table.c.name.desc().nullslast())
+            stmt = select([users_table]).order_by(
+                users_table.c.name.desc().nullslast())
 
         .. seealso::
 
@@ -3778,7 +3782,7 @@ class Over(ColumnElement):
             ROW_NUMBER() OVER(ORDER BY some_column
             RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)
 
-        A value of None indicates "unbounded", a
+        A value of ``None`` indicates "unbounded", a
         value of zero indicates "current row", and negative / positive
         integers indicate "preceding" and "following":
 
@@ -3810,8 +3814,8 @@ class Over(ColumnElement):
          of such, that will be used as the ORDER BY clause
          of the OVER construct.
         :param range\_: optional range clause for the window.  This is a
-         tuple value which can contain integer values or None, and will
-         render a RANGE BETWEEN PRECEDING / FOLLOWING clause
+         tuple value which can contain integer values or ``None``,
+         and will render a RANGE BETWEEN PRECEDING / FOLLOWING clause.
 
          .. versionadded:: 1.1
 
diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py
index 7b723f371..6fff26842 100644
--- a/lib/sqlalchemy/sql/functions.py
+++ b/lib/sqlalchemy/sql/functions.py
@@ -58,7 +58,7 @@ def register_function(identifier, fn, package="_default"):
     if identifier in reg:
         util.warn(
             "The GenericFunction '{}' is already registered and "
-            "is going to be overriden.".format(identifier)
+            "is going to be overridden.".format(identifier)
         )
     reg[identifier] = fn
 
@@ -125,7 +125,7 @@ class FunctionElement(Executable, ColumnElement, FromClause):
 
     @property
     def columns(self):
-        """The set of columns exported by this :class:`.FunctionElement`.
+        r"""The set of columns exported by this :class:`.FunctionElement`.
 
         Function objects currently have no result column names built in;
         this method returns a single-element column collection with
@@ -951,7 +951,7 @@ class user(AnsiFunction):
 
 
 class array_agg(GenericFunction):
-    """support for the ARRAY_AGG function.
+    """Support for the ARRAY_AGG function.
 
     The ``func.array_agg(expr)`` construct returns an expression of
     type :class:`_types.ARRAY`.
@@ -1011,7 +1011,7 @@ class OrderedSetAgg(GenericFunction):
 
 
 class mode(OrderedSetAgg):
-    """implement the ``mode`` ordered-set aggregate function.
+    """Implement the ``mode`` ordered-set aggregate function.
 
     This function must be used with the :meth:`.FunctionElement.within_group`
     modifier to supply a sort expression to operate upon.
@@ -1026,7 +1026,7 @@ class mode(OrderedSetAgg):
 
 
 class percentile_cont(OrderedSetAgg):
-    """implement the ``percentile_cont`` ordered-set aggregate function.
+    """Implement the ``percentile_cont`` ordered-set aggregate function.
 
     This function must be used with the :meth:`.FunctionElement.within_group`
     modifier to supply a sort expression to operate upon.
@@ -1044,7 +1044,7 @@ class percentile_cont(OrderedSetAgg):
 
 
 class percentile_disc(OrderedSetAgg):
-    """implement the ``percentile_disc`` ordered-set aggregate function.
+    """Implement the ``percentile_disc`` ordered-set aggregate function.
 
     This function must be used with the :meth:`.FunctionElement.within_group`
     modifier to supply a sort expression to operate upon.
diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py
index 1bd63f285..85db88345 100644
--- a/lib/sqlalchemy/sql/operators.py
+++ b/lib/sqlalchemy/sql/operators.py
@@ -124,7 +124,7 @@ class Operators(object):
     def op(
         self, opstring, precedence=0, is_comparison=False, return_type=None
     ):
-        """produce a generic operator function.
+        """Produce a generic operator function.
 
         e.g.::
 
@@ -721,7 +721,7 @@ class ColumnOperators(Operators):
 
             somecolumn LIKE :param || '%' ESCAPE '/'
 
-          With the value of :param as ``"foo/%bar"``.
+          With the value of ``:param`` as ``"foo/%bar"``.
 
           .. versionadded:: 1.2
 
@@ -809,7 +809,7 @@ class ColumnOperators(Operators):
 
             somecolumn LIKE '%' || :param ESCAPE '/'
 
-          With the value of :param as ``"foo/%bar"``.
+          With the value of ``:param`` as ``"foo/%bar"``.
 
           .. versionadded:: 1.2
 
@@ -897,7 +897,7 @@ class ColumnOperators(Operators):
 
             somecolumn LIKE '%' || :param || '%' ESCAPE '/'
 
-          With the value of :param as ``"foo/%bar"``.
+          With the value of ``:param`` as ``"foo/%bar"``.
 
           .. versionadded:: 1.2
 
diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index f6d8cfb1c..3df1c9f91 100644
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -327,7 +327,8 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
     :param implicit_returning: True by default - indicates that
         RETURNING can be used by default to fetch newly inserted primary key
         values, for backends which support this.  Note that
-        create_engine() also provides an implicit_returning flag.
+        :func:`_sa.create_engine` also provides an ``implicit_returning``
+        flag.
 
     :param include_columns: A list of strings indicating a subset of
         columns to be loaded via the ``autoload`` operation; table columns who
@@ -1250,13 +1251,13 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause):
                 :ref:`server_defaults` - complete discussion of server side
                 defaults
 
-        :param server_onupdate:   A :class:`.FetchedValue` instance
-             representing a database-side default generation function,
-             such as a trigger. This
-             indicates to SQLAlchemy that a newly generated value will be
-             available after updates. This construct does not actually
-             implement any kind of generation function within the database,
-             which instead must be specified separately.
+        :param server_onupdate: A :class:`.FetchedValue` instance
+            representing a database-side default generation function,
+            such as a trigger. This
+            indicates to SQLAlchemy that a newly generated value will be
+            available after updates. This construct does not actually
+            implement any kind of generation function within the database,
+            which instead must be specified separately.
 
             .. seealso::
 
@@ -1547,7 +1548,7 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause):
     def copy(self, **kw):
         """Create a copy of this ``Column``, uninitialized.
 
-        This is used in ``Table.tometadata``.
+        This is used in :meth:`_schema.Table.tometadata`.
 
         """
 
@@ -2216,7 +2217,7 @@ class ColumnDefault(DefaultGenerator):
     """
 
     def __init__(self, arg, **kwargs):
-        """"Construct a new :class:`.ColumnDefault`.
+        """Construct a new :class:`.ColumnDefault`.
 
 
         :param arg: argument representing the default value.
@@ -2345,7 +2346,7 @@ class IdentityOptions(object):
          or minvalue has been reached.
         :param cache: optional integer value; number of future values in the
          sequence which are calculated in advance.
-        :param order: optional boolean value; if true, renders the
+        :param order: optional boolean value; if ``True``, renders the
          ORDER keyword.
         :param data_type: The type to be returned by the sequence.
 
@@ -2495,7 +2496,7 @@ class Sequence(IdentityOptions, roles.StatementRole, DefaultGenerator):
 
          .. versionadded:: 1.1.12
 
-        :param order: optional boolean value; if true, renders the
+        :param order: optional boolean value; if ``True``, renders the
          ORDER keyword, understood by Oracle, indicating the sequence is
          definitively ordered.   May be necessary to provide deterministic
          ordering using Oracle RAC.
@@ -3330,7 +3331,7 @@ class ForeignKeyConstraint(ColumnCollectionConstraint):
         This list is either the original string arguments sent
         to the constructor of the :class:`_schema.ForeignKeyConstraint`,
         or if the constraint has been initialized with :class:`_schema.Column`
-        objects, is the string .key of each element.
+        objects, is the string ``.key`` of each element.
 
         .. versionadded:: 1.0.0
 
@@ -3861,12 +3862,14 @@ class MetaData(SchemaItem):
 
         :param bind:
           An Engine or Connection to bind to.  May also be a string or URL
-          instance, these are passed to create_engine() and this MetaData will
+          instance, these are passed to :func:`_sa.create_engine` and
+          this :class:`_schema.MetaData` will
           be bound to the resulting engine.
 
         :param reflect:
           Optional, automatically load all tables from the bound database.
-          Defaults to False. ``bind`` is required when this option is set.
+          Defaults to False. :paramref:`_schema.MetaData.bind` is required
+          when this option is set.
 
         :param schema:
            The default schema to use for the :class:`_schema.Table`,
@@ -4532,15 +4535,15 @@ class Computed(FetchedValue, SchemaItem):
           Optional, controls how this column should be persisted by the
           database.   Possible values are:
 
-          * None, the default, it will use the default persistence defined
-            by the database.
-          * True, will render ``GENERATED ALWAYS AS ... STORED``, or the
-            equivalent for the target database if supported
-          * False, will render ``GENERATED ALWAYS AS ... VIRTUAL``, or the
+          * ``None``, the default, it will use the default persistence
+            defined by the database.
+          * ``True``, will render ``GENERATED ALWAYS AS ... STORED``, or the
             equivalent for the target database if supported.
+          * ``False``, will render ``GENERATED ALWAYS AS ... VIRTUAL``, or
+            the equivalent for the target database if supported.
 
           Specifying ``True`` or ``False`` may raise an error when the DDL
-          is emitted to the target database if the databse does not support
+          is emitted to the target database if the database does not support
           that persistence option.   Leaving this parameter at its default
           of ``None`` is guaranteed to succeed for all databases that support
           ``GENERATED ALWAYS AS``.
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index 54f293967..bf6f20436 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -77,7 +77,7 @@ def subquery(alias, *args, **kwargs):
     r"""Return an :class:`.Subquery` object derived
     from a :class:`_expression.Select`.
 
-    :param name: the alias name for the subquery
+    :param alias: the alias name for the subquery
 
     :param \*args, \**kwargs:  all other arguments are passed through to the
      :func:`_expression.select` function.
@@ -143,7 +143,7 @@ class ReturnsRows(roles.ReturnsRowsRole, ClauseElement):
 
         .. versionadded:: 1.4
 
-        .. seealso:
+        .. seealso::
 
             :attr:`_expression.FromClause.exported_columns`
 
@@ -154,7 +154,7 @@ class ReturnsRows(roles.ReturnsRowsRole, ClauseElement):
 
 
 class Selectable(ReturnsRows):
-    """mark a class as being selectable.
+    """Mark a class as being selectable.
 
     """
 
@@ -170,7 +170,7 @@ class Selectable(ReturnsRows):
         raise NotImplementedError()
 
     def lateral(self, name=None):
-        """Return a LATERAL alias of this :class:`expression.Selectable`.
+        """Return a LATERAL alias of this :class:`_expression.Selectable`.
 
         The return value is the :class:`_expression.Lateral` construct also
         provided by the top-level :func:`_expression.lateral` function.
@@ -192,7 +192,8 @@ class Selectable(ReturnsRows):
     )
     @util.preload_module("sqlalchemy.sql.util")
     def replace_selectable(self, old, alias):
-        """replace all occurrences of FromClause 'old' with the given Alias
+        """Replace all occurrences of :class:`_expression.FromClause`
+        'old' with the given :class:`_expression.Alias`
         object, returning a copy of this :class:`_expression.FromClause`.
 
         """
@@ -201,29 +202,29 @@ class Selectable(ReturnsRows):
     def corresponding_column(self, column, require_embedded=False):
         """Given a :class:`_expression.ColumnElement`, return the exported
         :class:`_expression.ColumnElement` object from the
-        :attr:`expression.Selectable.exported_columns`
-        collection of this :class:`expression.Selectable`
+        :attr:`_expression.Selectable.exported_columns`
+        collection of this :class:`_expression.Selectable`
         which corresponds to that
         original :class:`_expression.ColumnElement` via a common ancestor
         column.
 
         :param column: the target :class:`_expression.ColumnElement`
-                      to be matched
+                      to be matched.
 
         :param require_embedded: only return corresponding columns for
          the given :class:`_expression.ColumnElement`, if the given
          :class:`_expression.ColumnElement`
          is actually present within a sub-element
-         of this :class:`expression.Selectable`.
+         of this :class:`_expression.Selectable`.
          Normally the column will match if
          it merely shares a common ancestor with one of the exported
-         columns of this :class:`expression.Selectable`.
+         columns of this :class:`_expression.Selectable`.
 
         .. seealso::
 
-            :attr:`expression.Selectable.exported_columns` - the
+            :attr:`_expression.Selectable.exported_columns` - the
             :class:`_expression.ColumnCollection`
-            that is used for the operation
+            that is used for the operation.
 
             :meth:`_expression.ColumnCollection.corresponding_column`
             - implementation
@@ -353,7 +354,7 @@ class HasHints(object):
     ]
 
     def with_statement_hint(self, text, dialect_name="*"):
-        """add a statement hint to this :class:`_expression.Select` or
+        """Add a statement hint to this :class:`_expression.Select` or
         other selectable object.
 
         This method is similar to :meth:`_expression.Select.with_hint`
@@ -371,9 +372,9 @@ class HasHints(object):
 
             :meth:`_expression.Select.with_hint`
 
-            :meth:.`.Select.prefix_with` - generic SELECT prefixing which also
-            can suit some database-specific HINT syntaxes such as MySQL
-            optimizer hints
+            :meth:`_expression.Select.prefix_with` - generic SELECT prefixing
+            which also can suit some database-specific HINT syntaxes such as
+            MySQL optimizer hints
 
         """
         return self.with_hint(None, text, dialect_name)
@@ -468,7 +469,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
     _use_schema_map = False
 
     def select(self, whereclause=None, **params):
-        """return a SELECT of this :class:`_expression.FromClause`.
+        """Return a SELECT of this :class:`_expression.FromClause`.
 
         .. seealso::
 
@@ -572,7 +573,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
         return Join(self, right, onclause, True, full)
 
     def alias(self, name=None, flat=False):
-        """return an alias of this :class:`_expression.FromClause`.
+        """Return an alias of this :class:`_expression.FromClause`.
 
         E.g.::
 
@@ -609,8 +610,8 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
         return TableSample._construct(self, sampling, name, seed)
 
     def is_derived_from(self, fromclause):
-        """Return True if this FromClause is 'derived' from the given
-        FromClause.
+        """Return ``True`` if this :class:`_expression.FromClause` is
+        'derived' from the given ``FromClause``.
 
         An example would be an Alias of a Table is derived from that Table.
 
@@ -621,8 +622,8 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
         return fromclause in self._cloned_set
 
     def _is_lexical_equivalent(self, other):
-        """Return True if this FromClause and the other represent
-        the same lexical identity.
+        """Return ``True`` if this :class:`_expression.FromClause` and
+        the other represent the same lexical identity.
 
         This tests if either one is a copy of the other, or
         if they are the same via annotation identity.
@@ -632,7 +633,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
 
     @property
     def description(self):
-        """a brief description of this FromClause.
+        """A brief description of this :class:`_expression.FromClause`.
 
         Used primarily for error message formatting.
 
@@ -648,7 +649,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
     def exported_columns(self):
         """A :class:`_expression.ColumnCollection`
         that represents the "exported"
-        columns of this :class:`expression.Selectable`.
+        columns of this :class:`_expression.Selectable`.
 
         The "exported" columns for a :class:`_expression.FromClause`
         object are synonymous
@@ -656,9 +657,9 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
 
         .. versionadded:: 1.4
 
-        .. seealso:
+        .. seealso::
 
-            :attr:`expression.Selectable.exported_columns`
+            :attr:`_expression.Selectable.exported_columns`
 
             :attr:`_expression.SelectBase.exported_columns`
 
@@ -694,7 +695,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
 
             stmt.filter_by(address='some address')
 
-        It defaults to the .c collection, however internally it can
+        It defaults to the ``.c`` collection, however internally it can
         be overridden using the "entity_namespace" annotation to deliver
         alternative results.
 
@@ -703,24 +704,26 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
 
     @util.memoized_property
     def primary_key(self):
-        """Return the collection of Column objects which comprise the
-        primary key of this FromClause."""
+        """Return the collection of :class:`_schema.Column` objects
+        which comprise the primary key of this FromClause.
 
+        """
         self._init_collections()
         self._populate_column_collection()
         return self.primary_key
 
     @util.memoized_property
     def foreign_keys(self):
-        """Return the collection of ForeignKey objects which this
-        FromClause references."""
+        """Return the collection of :class:`_schema.ForeignKey` objects
+        which this FromClause references.
 
+        """
         self._init_collections()
         self._populate_column_collection()
         return self.foreign_keys
 
     def _reset_column_collection(self):
-        """Reset the attributes linked to the FromClause.c attribute.
+        """Reset the attributes linked to the ``FromClause.c`` attribute.
 
         This collection is separate from all the other memoized things
         as it has shown to be sensitive to being cleared out in situations
@@ -792,7 +795,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
 
 
 class Join(roles.DMLTableRole, FromClause):
-    """represent a ``JOIN`` construct between two
+    """Represent a ``JOIN`` construct between two
     :class:`_expression.FromClause`
     elements.
 
@@ -857,7 +860,7 @@ class Join(roles.DMLTableRole, FromClause):
         The returned object is an instance of :class:`_expression.Join`.
 
         Similar functionality is also available via the
-        :meth:`_expression.FromClause.outerjoin()` method on any
+        :meth:`_expression.FromClause.outerjoin` method on any
         :class:`_expression.FromClause`.
 
         :param left: The left side of the join.
@@ -922,9 +925,9 @@ class Join(roles.DMLTableRole, FromClause):
         .. seealso::
 
             :meth:`_expression.FromClause.join` - method form,
-            based on a given left side
+            based on a given left side.
 
-            :class:`_expression.Join` - the type of object produced
+            :class:`_expression.Join` - the type of object produced.
 
         """
 
@@ -984,7 +987,7 @@ class Join(roles.DMLTableRole, FromClause):
     def _join_condition(
         cls, a, b, a_subset=None, consider_as_foreign_keys=None
     ):
-        """create a join condition between two tables or selectables.
+        """Create a join condition between two tables or selectables.
 
         e.g.::
 
@@ -1169,7 +1172,7 @@ class Join(roles.DMLTableRole, FromClause):
 
     @util.preload_module("sqlalchemy.sql.util")
     def alias(self, name=None, flat=False):
-        r"""return an alias of this :class:`_expression.Join`.
+        r"""Return an alias of this :class:`_expression.Join`.
 
         The default behavior here is to first produce a SELECT
         construct from this :class:`_expression.Join`, then to produce an
@@ -1376,7 +1379,7 @@ class AliasedReturnsRows(NoInit, FromClause):
 
     @property
     def original(self):
-        """legacy for dialects that are referring to Alias.original"""
+        """Legacy for dialects that are referring to Alias.original."""
         return self.element
 
     def is_derived_from(self, fromclause):
@@ -1675,7 +1678,7 @@ class CTE(Generative, HasPrefixes, HasSuffixes, AliasedReturnsRows):
         :class:`_expression.CTE`.
 
         This method is a CTE-specific specialization of the
-        :class:`_expression.FromClause.alias` method.
+        :meth:`_expression.FromClause.alias` method.
 
         .. seealso::
 
@@ -1754,8 +1757,8 @@ class HasCTE(roles.HasCTERole):
            In particular - MATERIALIZED and NOT MATERIALIZED.
 
         :param name: name given to the common table expression.  Like
-         :meth:`._FromClause.alias`, the name can be left as ``None``
-         in which case an anonymous symbol will be used at query
+         :meth:`_expression.FromClause.alias`, the name can be left as
+         ``None`` in which case an anonymous symbol will be used at query
          compile time.
         :param recursive: if ``True``, will render ``WITH RECURSIVE``.
          A recursive common table expression is intended to be used in
@@ -1896,7 +1899,7 @@ class Subquery(AliasedReturnsRows):
 
     A :class:`.Subquery` is created by invoking the
     :meth:`_expression.SelectBase.subquery` method, or for convenience the
-    :class:`_expression.SelectBase.alias` method, on any
+    :meth:`_expression.SelectBase.alias` method, on any
     :class:`_expression.SelectBase` subclass
     which includes :class:`_expression.Select`,
     :class:`_expression.CompoundSelect`, and
@@ -2048,8 +2051,8 @@ class TableClause(roles.DMLTableRole, Immutable, FromClause):
     def __init__(self, name, *columns, **kw):
         """Produce a new :class:`_expression.TableClause`.
 
-        The object returned is an instance of :class:`_expression.TableClause`
-        , which
+        The object returned is an instance of
+        :class:`_expression.TableClause`, which
         represents the "syntactical" portion of the schema-level
         :class:`_schema.Table` object.
         It may be used to construct lightweight table constructs.
@@ -2212,7 +2215,7 @@ class ForUpdateArg(ClauseElement):
 
 
 class Values(Generative, FromClause):
-    """represent a ``VALUES`` construct that can be used as a FROM element
+    """Represent a ``VALUES`` construct that can be used as a FROM element
     in a statement.
 
     The :class:`_expression.Values` object is created from the
@@ -2283,7 +2286,7 @@ class Values(Generative, FromClause):
         one with the given name.
 
         This method is a VALUES-specific specialization of the
-        :class:`_expression.FromClause.alias` method.
+        :meth:`_expression.FromClause.alias` method.
 
         .. seealso::
 
@@ -2390,7 +2393,7 @@ class SelectBase(
     def exported_columns(self):
         """A :class:`_expression.ColumnCollection`
         that represents the "exported"
-        columns of this :class:`expression.Selectable`.
+        columns of this :class:`_expression.Selectable`.
 
         The "exported" columns for a :class:`_expression.SelectBase`
         object are synonymous
@@ -2398,9 +2401,9 @@ class SelectBase(
 
         .. versionadded:: 1.4
 
-        .. seealso:
+        .. seealso::
 
-            :attr:`expression.Selectable.exported_columns`
+            :attr:`_expression.Selectable.exported_columns`
 
             :attr:`_expression.FromClause.exported_columns`
 
@@ -2436,7 +2439,7 @@ class SelectBase(
         "creates a subquery that should be explicit.  "
         "Please call :meth:`_expression.SelectBase.subquery` "
         "first in order to create "
-        "a subquery, which then can be seleted.",
+        "a subquery, which then can be selected.",
     )
     def select(self, *arg, **kw):
         return self._implicit_subquery.select(*arg, **kw)
@@ -2480,7 +2483,7 @@ class SelectBase(
         return self.scalar_subquery()
 
     def scalar_subquery(self):
-        """return a 'scalar' representation of this selectable, which can be
+        """Return a 'scalar' representation of this selectable, which can be
         used as a column expression.
 
         Typically, a select statement which has only one column in its columns
@@ -2503,7 +2506,7 @@ class SelectBase(
         return ScalarSelect(self)
 
     def label(self, name):
-        """return a 'scalar' representation of this selectable, embedded as a
+        """Return a 'scalar' representation of this selectable, embedded as a
         subquery with a label.
 
         .. seealso::
@@ -2514,7 +2517,7 @@ class SelectBase(
         return self.scalar_subquery().label(name)
 
     def lateral(self, name=None):
-        """Return a LATERAL alias of this :class:`expression.Selectable`.
+        """Return a LATERAL alias of this :class:`_expression.Selectable`.
 
         The return value is the :class:`_expression.Lateral` construct also
         provided by the top-level :func:`_expression.lateral` function.
@@ -2535,8 +2538,9 @@ class SelectBase(
     def subquery(self, name=None):
         """Return a subquery of this :class:`_expression.SelectBase`.
 
-        A subquery is from a SQL perspective a parentheized, named construct
-        that can be placed in the FROM clause of another SELECT statement.
+        A subquery is from a SQL perspective a parenthesized, named
+        construct that can be placed in the FROM clause of another
+        SELECT statement.
 
         Given a SELECT statement such as::
 
@@ -2836,7 +2840,7 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
         return self._label_style is LABEL_STYLE_TABLENAME_PLUS_COL
 
     def apply_labels(self):
-        """return a new selectable with the 'use_labels' flag set to True.
+        """Return a new selectable with the 'use_labels' flag set to True.
 
         This will result in column expressions being generated using labels
         against their table name, such as "SELECT somecolumn AS
@@ -2940,7 +2944,7 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
 
     @_generative
     def limit(self, limit):
-        """return a new selectable with the given LIMIT criterion
+        """Return a new selectable with the given LIMIT criterion
         applied.
 
         This is a numerical value which usually renders as a ``LIMIT``
@@ -2960,7 +2964,7 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
 
     @_generative
     def offset(self, offset):
-        """return a new selectable with the given OFFSET criterion
+        """Return a new selectable with the given OFFSET criterion
         applied.
 
 
@@ -2982,14 +2986,14 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
 
     @_generative
     def order_by(self, *clauses):
-        r"""return a new selectable with the given list of ORDER BY
+        r"""Return a new selectable with the given list of ORDER BY
         criterion applied.
 
         e.g.::
 
             stmt = select([table]).order_by(table.c.id, table.c.name)
 
-        :param \*order_by: a series of :class:`_expression.ColumnElement`
+        :param \*clauses: a series of :class:`_expression.ColumnElement`
          constructs
          which will be used to generate an ORDER BY clause.
 
@@ -3009,7 +3013,7 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
 
     @_generative
     def group_by(self, *clauses):
-        r"""return a new selectable with the given list of GROUP BY
+        r"""Return a new selectable with the given list of GROUP BY
         criterion applied.
 
         e.g.::
@@ -3017,7 +3021,7 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
             stmt = select([table.c.name, func.max(table.c.stat)]).\
             group_by(table.c.name)
 
-        :param \*group_by: a series of :class:`_expression.ColumnElement`
+        :param \*clauses: a series of :class:`_expression.ColumnElement`
          constructs
          which will be used to generate an GROUP BY clause.
 
@@ -3049,7 +3053,7 @@ class CompoundSelectState(CompileState):
 
 class CompoundSelect(HasCompileState, GenerativeSelect):
     """Forms the basis of ``UNION``, ``UNION ALL``, and other
-        SELECT-based set operations.
+    SELECT-based set operations.
 
 
     .. seealso::
@@ -3111,12 +3115,12 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
         A similar :func:`union()` method is available on all
         :class:`_expression.FromClause` subclasses.
 
-        \*selects
+        :param \*selects:
           a list of :class:`_expression.Select` instances.
 
-        \**kwargs
-           available keyword arguments are the same as those of
-           :func:`select`.
+        :param \**kwargs:
+          available keyword arguments are the same as those of
+          :func:`select`.
 
         """
         return CompoundSelect(CompoundSelect.UNION, *selects, **kwargs)
@@ -3131,10 +3135,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
         A similar :func:`union_all()` method is available on all
         :class:`_expression.FromClause` subclasses.
 
-        \*selects
+        :param \*selects:
           a list of :class:`_expression.Select` instances.
 
-        \**kwargs
+        :param \**kwargs:
           available keyword arguments are the same as those of
           :func:`select`.
 
@@ -3148,10 +3152,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
         The returned object is an instance of
         :class:`_expression.CompoundSelect`.
 
-        \*selects
+        :param \*selects:
           a list of :class:`_expression.Select` instances.
 
-        \**kwargs
+        :param \**kwargs:
           available keyword arguments are the same as those of
           :func:`select`.
 
@@ -3165,10 +3169,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
         The returned object is an instance of
         :class:`_expression.CompoundSelect`.
 
-        \*selects
+        :param \*selects:
           a list of :class:`_expression.Select` instances.
 
-        \**kwargs
+        :param \**kwargs:
           available keyword arguments are the same as those of
           :func:`select`.
 
@@ -3182,10 +3186,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
         The returned object is an instance of
         :class:`_expression.CompoundSelect`.
 
-        \*selects
+        :param \*selects:
           a list of :class:`_expression.Select` instances.
 
-        \**kwargs
+        :param \**kwargs:
           available keyword arguments are the same as those of
           :func:`select`.
 
@@ -3199,10 +3203,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
         The returned object is an instance of
         :class:`_expression.CompoundSelect`.
 
-        \*selects
+        :param \*selects:
           a list of :class:`_expression.Select` instances.
 
-        \**kwargs
+        :param \**kwargs:
           available keyword arguments are the same as those of
           :func:`select`.
 
@@ -3318,7 +3322,7 @@ class DeprecatedSelectGenerations(object):
         "method :meth:`_expression.Select.correlate`.",
     )
     def append_correlation(self, fromclause):
-        """append the given correlation expression to this select()
+        """Append the given correlation expression to this select()
         construct.
 
         This is an **in-place** mutation method; the
@@ -3337,7 +3341,7 @@ class DeprecatedSelectGenerations(object):
         "method :meth:`_expression.Select.column`.",
     )
     def append_column(self, column):
-        """append the given column expression to the columns clause of this
+        """Append the given column expression to the columns clause of this
         select() construct.
 
         E.g.::
@@ -3363,7 +3367,7 @@ class DeprecatedSelectGenerations(object):
         "method :meth:`_expression.Select.prefix_with`.",
     )
     def append_prefix(self, clause):
-        """append the given columns clause prefix expression to this select()
+        """Append the given columns clause prefix expression to this select()
         construct.
 
         This is an **in-place** mutation method; the
@@ -3382,7 +3386,7 @@ class DeprecatedSelectGenerations(object):
         "method :meth:`_expression.Select.where`.",
     )
     def append_whereclause(self, whereclause):
-        """append the given expression to this select() construct's WHERE
+        """Append the given expression to this select() construct's WHERE
         criterion.
 
         The expression will be joined to existing WHERE criterion via AND.
@@ -3402,7 +3406,7 @@ class DeprecatedSelectGenerations(object):
         "method :meth:`_expression.Select.having`.",
     )
     def append_having(self, having):
-        """append the given expression to this select() construct's HAVING
+        """Append the given expression to this select() construct's HAVING
         criterion.
 
         The expression will be joined to existing HAVING criterion via AND.
@@ -3423,8 +3427,8 @@ class DeprecatedSelectGenerations(object):
         "method :meth:`_expression.Select.select_from`.",
     )
     def append_from(self, fromclause):
-        """append the given FromClause expression to this select() construct's
-        FROM clause.
+        """Append the given :class:`_expression.FromClause` expression
+        to this select() construct's FROM clause.
 
         This is an **in-place** mutation method; the
         :meth:`_expression.Select.select_from` method is preferred,
@@ -3689,7 +3693,7 @@ class SelectState(util.MemoizedSlots, CompileState):
                 "from, there are multiple FROMS which can "
                 "join to this entity. Please use the .select_from() "
                 "method to establish an explicit left side, as well as "
-                "providing an explcit ON clause if not present already to "
+                "providing an explicit ON clause if not present already to "
                 "help resolve the ambiguity."
             )
         elif not indexes:
@@ -3697,7 +3701,7 @@ class SelectState(util.MemoizedSlots, CompileState):
                 "Don't know how to join to %r. "
                 "Please use the .select_from() "
                 "method to establish an explicit left side, as well as "
-                "providing an explcit ON clause if not present already to "
+                "providing an explicit ON clause if not present already to "
                 "help resolve the ambiguity." % (right,)
             )
         return left, replace_from_obj_index
@@ -3855,8 +3859,8 @@ class Select(
         suffixes=None,
         **kwargs
     ):
-        """Construct a new :class:`_expression.Select` using the 1.x style API
-        .
+        """Construct a new :class:`_expression.Select` using the 1.x style
+        API.
 
         Similar functionality is also available via the
         :meth:`_expression.FromClause.select` method on any
@@ -3865,8 +3869,8 @@ class Select(
         All arguments which accept :class:`_expression.ClauseElement`
         arguments also
         accept string arguments, which will be converted as appropriate into
-        either :func:`_expression.text()` or
-        :func:`_expression.literal_column()` constructs.
+        either :func:`_expression.text` or
+        :func:`_expression.literal_column` constructs.
 
         .. seealso::
 
@@ -4035,7 +4039,7 @@ class Select(
           for each column in the columns clause, which qualify each
           column with its parent table's (or aliases) name so that name
           conflicts between columns in different tables don't occur.
-          The format of the label is <tablename>_<column>.  The "c"
+          The format of the label is ``<tablename>_<column>``.  The "c"
           collection of the resulting :class:`_expression.Select`
           object will use these
           names as well for targeting column members.
@@ -4112,13 +4116,16 @@ class Select(
 
     @property
     def froms(self):
-        """Return the displayed list of FromClause elements."""
+        """Return the displayed list of :class:`_expression.FromClause`
+        elements.
 
+        """
         return self._compile_state_factory(self, None)._get_display_froms()
 
     @property
     def inner_columns(self):
-        """an iterator of all ColumnElement expressions which would
+        """An iterator of all :class:`_expression.ColumnElement`
+        expressions which would
         be rendered into the columns clause of the resulting SELECT statement.
 
         This method is legacy as of 1.4 and is superseded by the
@@ -4198,17 +4205,17 @@ class Select(
 
     @_generative
     def add_columns(self, *columns):
-        """return a new select() construct with the given column expressions
-            added to its columns clause.
+        """Return a new :func:`_expression.select` construct with
+        the given column expressions added to its columns clause.
 
-            E.g.::
+        E.g.::
 
-                my_select = my_select.add_columns(table.c.new_column)
+            my_select = my_select.add_columns(table.c.new_column)
 
-            See the documentation for
-            :meth:`_expression.Select.with_only_columns`
-            for guidelines on adding /replacing the columns of a
-            :class:`_expression.Select` object.
+        See the documentation for
+        :meth:`_expression.Select.with_only_columns`
+        for guidelines on adding /replacing the columns of a
+        :class:`_expression.Select` object.
 
         """
         # memoizations should be cleared here as of
@@ -4238,24 +4245,24 @@ class Select(
         ":meth:`_expression.Select.add_columns`",
     )
     def column(self, column):
-        """return a new select() construct with the given column expression
-           added to its columns clause.
+        """Return a new :func:`_expression.select` construct with
+        the given column expression added to its columns clause.
 
-           E.g.::
+        E.g.::
 
-                my_select = my_select.column(table.c.new_column)
+            my_select = my_select.column(table.c.new_column)
 
-           See the documentation for
-           :meth:`_expression.Select.with_only_columns`
-           for guidelines on adding /replacing the columns of a
-           :class:`_expression.Select` object.
+        See the documentation for
+        :meth:`_expression.Select.with_only_columns`
+        for guidelines on adding /replacing the columns of a
+        :class:`_expression.Select` object.
 
         """
         return self.add_columns(column)
 
     @util.preload_module("sqlalchemy.sql.util")
     def reduce_columns(self, only_synonyms=True):
-        """Return a new :func`.select` construct with redundantly
+        """Return a new :func:`_expression.select` construct with redundantly
         named, equivalently-valued columns removed from the columns clause.
 
         "Redundant" here means two columns where one refers to the
@@ -4263,8 +4270,8 @@ class Select(
         comparison in the WHERE clause of the statement.   The primary purpose
         of this method is to automatically construct a select statement
         with all uniquely-named columns, without the need to use
-        table-qualified labels as :meth:`_expression.Select.apply_labels` does
-        .
+        table-qualified labels as :meth:`_expression.Select.apply_labels`
+        does.
 
         When columns are omitted based on foreign key, the referred-to
         column is the one that's kept.  When columns are omitted based on
@@ -4371,8 +4378,8 @@ class Select(
 
     @property
     def whereclause(self):
-        """Return the completed WHERE clause for this :class:`.Select`
-        statement.
+        """Return the completed WHERE clause for this
+        :class:`_expression.Select` statement.
 
         This assembles the current collection of WHERE criteria
         into a single :class:`_expression.BooleanClauseList` construct.
@@ -4390,7 +4397,8 @@ class Select(
 
     @_generative
     def where(self, whereclause):
-        """return a new select() construct with the given expression added to
+        """Return a new :func:`_expression.select` construct with
+        the given expression added to
         its WHERE clause, joined to the existing clause via AND, if any.
 
         """
@@ -4401,7 +4409,8 @@ class Select(
 
     @_generative
     def having(self, having):
-        """return a new select() construct with the given expression added to
+        """Return a new :func:`_expression.select` construct with
+        the given expression added to
         its HAVING clause, joined to the existing clause via AND, if any.
 
         """
@@ -4411,8 +4420,8 @@ class Select(
 
     @_generative
     def distinct(self, *expr):
-        r"""Return a new select() construct which will apply DISTINCT to its
-        columns clause.
+        r"""Return a new :func:`_expression.select` construct which
+        will apply DISTINCT to its columns clause.
 
         :param \*expr: optional column expressions.  When present,
          the PostgreSQL dialect will render a ``DISTINCT ON (<expressions>>)``
@@ -4432,7 +4441,7 @@ class Select(
 
     @_generative
     def select_from(self, *froms):
-        r"""return a new :func:`_expression.select` construct with the
+        r"""Return a new :func:`_expression.select` construct with the
         given FROM expression(s)
         merged into its list of FROM objects.
 
@@ -4475,7 +4484,7 @@ class Select(
 
     @_generative
     def correlate(self, *fromclauses):
-        r"""return a new :class:`_expression.Select`
+        r"""Return a new :class:`_expression.Select`
         which will correlate the given FROM
         clauses to that of an enclosing :class:`_expression.Select`.
 
@@ -4536,7 +4545,7 @@ class Select(
 
     @_generative
     def correlate_except(self, *fromclauses):
-        r"""return a new :class:`_expression.Select`
+        r"""Return a new :class:`_expression.Select`
         which will omit the given FROM
         clauses from the auto-correlation process.
 
@@ -4736,8 +4745,8 @@ class Select(
             return [name_for_col(c) for c in cols]
 
     def _generate_fromclause_column_proxies(self, subquery):
-        """generate column proxies to place in the exported .c collection
-        of a subquery."""
+        """Generate column proxies to place in the exported ``.c``
+        collection of a subquery."""
 
         keys_seen = set()
         prox = []
@@ -4785,8 +4794,8 @@ class Select(
         )
 
     def self_group(self, against=None):
-        """return a 'grouping' construct as per the ClauseElement
-        specification.
+        """Return a 'grouping' construct as per the
+        :class:`_expression.ClauseElement` specification.
 
         This produces an element that can be embedded in an expression. Note
         that this method is called automatically as needed when constructing
@@ -4802,41 +4811,43 @@ class Select(
             return SelectStatementGrouping(self)
 
     def union(self, other, **kwargs):
-        """return a SQL UNION of this select() construct against the given
-        selectable."""
+        """Return a SQL ``UNION`` of this select() construct against
+        the given selectable.
 
+        """
         return CompoundSelect._create_union(self, other, **kwargs)
 
     def union_all(self, other, **kwargs):
-        """return a SQL UNION ALL of this select() construct against the given
-        selectable.
+        """Return a SQL ``UNION ALL`` of this select() construct against
+        the given selectable.
 
         """
         return CompoundSelect._create_union_all(self, other, **kwargs)
 
     def except_(self, other, **kwargs):
-        """return a SQL EXCEPT of this select() construct against the given
-        selectable."""
+        """Return a SQL ``EXCEPT`` of this select() construct against
+        the given selectable.
 
+        """
         return CompoundSelect._create_except(self, other, **kwargs)
 
     def except_all(self, other, **kwargs):
-        """return a SQL EXCEPT ALL of this select() construct against the
-        given selectable.
+        """Return a SQL ``EXCEPT ALL`` of this select() construct against
+        the given selectable.
 
         """
         return CompoundSelect._create_except_all(self, other, **kwargs)
 
     def intersect(self, other, **kwargs):
-        """return a SQL INTERSECT of this select() construct against the given
-        selectable.
+        """Return a SQL ``INTERSECT`` of this select() construct against
+        the given selectable.
 
         """
         return CompoundSelect._create_intersect(self, other, **kwargs)
 
     def intersect_all(self, other, **kwargs):
-        """return a SQL INTERSECT ALL of this select() construct against the
-        given selectable.
+        """Return a SQL ``INTERSECT ALL`` of this select() construct
+        against the given selectable.
 
         """
         return CompoundSelect._create_intersect_all(self, other, **kwargs)
@@ -4968,7 +4979,7 @@ class Exists(UnaryExpression):
         return e
 
     def select_from(self, clause):
-        """return a new :class:`_expression.Exists` construct,
+        """Return a new :class:`_expression.Exists` construct,
         applying the given
         expression to the :meth:`_expression.Select.select_from`
         method of the select
@@ -4980,7 +4991,8 @@ class Exists(UnaryExpression):
         return e
 
     def where(self, clause):
-        """return a new exists() construct with the given expression added to
+        """Return a new :func:`_expression.exists` construct with the
+        given expression added to
         its WHERE clause, joined to the existing clause via AND, if any.
 
         """
@@ -4994,8 +5006,8 @@ class TextualSelect(SelectBase):
     :class:`_expression.SelectBase`
     interface.
 
-    This allows the :class:`_expression.TextClause` object to gain a ``.
-    c`` collection
+    This allows the :class:`_expression.TextClause` object to gain a
+    ``.c`` collection
     and other FROM-like capabilities such as
     :meth:`_expression.FromClause.alias`,
     :meth:`_expression.SelectBase.cte`, etc.
diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py
index 9cd9d5058..5d7f80b1b 100644
--- a/lib/sqlalchemy/sql/sqltypes.py
+++ b/lib/sqlalchemy/sql/sqltypes.py
@@ -594,7 +594,7 @@ class Numeric(_LookupExpressionAdapter, TypeEngine):
         type that is explicitly known to be a decimal type
         (e.g. ``DECIMAL``, ``NUMERIC``, others) and not a floating point
         type (e.g. ``FLOAT``, ``REAL``, others).
-        If the database column on the server is in fact a floating-point type
+        If the database column on the server is in fact a floating-point
         type, such as ``FLOAT`` or ``REAL``, use the :class:`.Float`
         type or a subclass, otherwise numeric coercion between
         ``float``/``Decimal`` may or may not function as expected.
@@ -1161,7 +1161,7 @@ class SchemaType(SchemaEventTarget):
         return self.metadata and self.metadata.bind or None
 
     def create(self, bind=None, checkfirst=False):
-        """Issue CREATE ddl for this type, if applicable."""
+        """Issue CREATE DDL for this type, if applicable."""
 
         if bind is None:
             bind = _bind_or_error(self)
@@ -1170,7 +1170,7 @@ class SchemaType(SchemaEventTarget):
             t.create(bind=bind, checkfirst=checkfirst)
 
     def drop(self, bind=None, checkfirst=False):
-        """Issue DROP ddl for this type, if applicable."""
+        """Issue DROP DDL for this type, if applicable."""
 
         if bind is None:
             bind = _bind_or_error(self)
@@ -1417,7 +1417,7 @@ class Enum(Emulated, String, SchemaType):
            default, the database value of the enumeration is used as the
            sorting function.
 
-            .. versionadded:: 1.3.8
+           .. versionadded:: 1.3.8
 
 
 
@@ -1808,11 +1808,9 @@ class Boolean(Emulated, TypeEngine, SchemaType):
              appropriate naming convention; see
              :ref:`constraint_naming_conventions` for background.
 
-           .. versionchanged:: 1.4 - this flag now defaults to False, meaning
-              no CHECK constraint is generated for a non-native enumerated
-              type.
-
-
+          .. versionchanged:: 1.4 - this flag now defaults to False, meaning
+             no CHECK constraint is generated for a non-native enumerated
+             type.
 
         :param name: if a CHECK constraint is generated, specify
           the name of the constraint.
@@ -2237,8 +2235,8 @@ class JSON(Indexable, TypeEngine):
         )
 
     While it is possible to use :attr:`_types.JSON.NULL` in this context, the
-    :attr:`_types.JSON.NULL` value will be returned as the value of the column
-    ,
+    :attr:`_types.JSON.NULL` value will be returned as the value of the
+    column,
     which in the context of the ORM or other repurposing of the default
     value, may not be desirable.  Using a SQL expression means the value
     will be re-fetched from the database within the context of retrieving
@@ -2273,7 +2271,7 @@ class JSON(Indexable, TypeEngine):
         self.none_as_null = none_as_null
 
     class JSONElementType(TypeEngine):
-        """common function for index / path elements in a JSON expression."""
+        """Common function for index / path elements in a JSON expression."""
 
         _integer = Integer()
         _string = String()
@@ -2599,7 +2597,7 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine):
     __visit_name__ = "ARRAY"
 
     zero_indexes = False
-    """if True, Python zero-based indexes should be interpreted as one-based
+    """If True, Python zero-based indexes should be interpreted as one-based
     on the SQL expression side."""
 
     class Comparator(Indexable.Comparator, Concatenable.Comparator):
diff --git a/lib/sqlalchemy/sql/traversals.py b/lib/sqlalchemy/sql/traversals.py
index ed0bfa27a..8d01b7ff7 100644
--- a/lib/sqlalchemy/sql/traversals.py
+++ b/lib/sqlalchemy/sql/traversals.py
@@ -287,7 +287,7 @@ class CacheKey(namedtuple("CacheKey", ["key", "bindparams"])):
         return None
 
     def to_offline_string(self, statement_cache, statement, parameters):
-        """generate an "offline string" form of this :class:`.CacheKey`
+        """Generate an "offline string" form of this :class:`.CacheKey`
 
         The "offline string" is basically the string SQL for the
         statement plus a repr of the bound parameter values in series.
@@ -295,8 +295,8 @@ class CacheKey(namedtuple("CacheKey", ["key", "bindparams"])):
         identities in order to work as a cache key, the "offline" version
         is suitable for a cache that will work for other processes as well.
 
-        The given "statement_cache" is a dictionary-like object where the
-        string form of the statement itself will be cached.  this dictionary
+        The given ``statement_cache`` is a dictionary-like object where the
+        string form of the statement itself will be cached.  This dictionary
         should be in a longer lived scope in order to reduce the time spent
         stringifying statements.
 
diff --git a/lib/sqlalchemy/sql/type_api.py b/lib/sqlalchemy/sql/type_api.py
index fe3634bad..83c7960ac 100644
--- a/lib/sqlalchemy/sql/type_api.py
+++ b/lib/sqlalchemy/sql/type_api.py
@@ -337,7 +337,7 @@ class TypeEngine(Traversible):
         )
 
     def bind_expression(self, bindvalue):
-        """"Given a bind value (i.e. a :class:`.BindParameter` instance),
+        """Given a bind value (i.e. a :class:`.BindParameter` instance),
         return a SQL expression in its place.
 
         This is typically a SQL function that wraps the existing bound
@@ -389,7 +389,7 @@ class TypeEngine(Traversible):
         """Return the corresponding type object from the underlying DB-API, if
         any.
 
-         This can be useful for calling ``setinputsizes()``, for example.
+        This can be useful for calling ``setinputsizes()``, for example.
 
         """
         return None
@@ -809,10 +809,10 @@ class TypeDecorator(SchemaEventTarget, TypeEngine):
           def copy(self, **kw):
               return MyType(self.impl.length)
 
-    The class-level "impl" attribute is required, and can reference any
-    TypeEngine class.  Alternatively, the load_dialect_impl() method
-    can be used to provide different type classes based on the dialect
-    given; in this case, the "impl" variable can reference
+    The class-level ``impl`` attribute is required, and can reference any
+    :class:`.TypeEngine` class.  Alternatively, the :meth:`load_dialect_impl`
+    method can be used to provide different type classes based on the dialect
+    given; in this case, the ``impl`` variable can reference
     ``TypeEngine`` as a placeholder.
 
     Types that receive a Python type that isn't similar to the ultimate type
@@ -914,7 +914,7 @@ class TypeDecorator(SchemaEventTarget, TypeEngine):
     coerce_to_is_types = (util.NoneType,)
     """Specify those Python types which should be coerced at the expression
     level to "IS <constant>" when compared using ``==`` (and same for
-    ``IS NOT`` in conjunction with ``!=``.
+    ``IS NOT`` in conjunction with ``!=``).
 
     For most SQLAlchemy types, this includes ``NoneType``, as well as
     ``bool``.
diff --git a/lib/sqlalchemy/sql/visitors.py b/lib/sqlalchemy/sql/visitors.py
index 904702003..56d3c93b3 100644
--- a/lib/sqlalchemy/sql/visitors.py
+++ b/lib/sqlalchemy/sql/visitors.py
@@ -181,7 +181,7 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)):
         ]
 
     Above, the :class:`.Case` class indicates its internal state as the
-    attributes named ``value``, ``whens``, and ``else\_``.    They each
+    attributes named ``value``, ``whens``, and ``else_``.    They each
     link to an :class:`.InternalTraversal` method which indicates the type
     of datastructure referred towards.
 
@@ -330,7 +330,7 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)):
     """
 
     dp_dialect_options = symbol("DO")
-    """visit a dialect options structure."""
+    """Visit a dialect options structure."""
 
     dp_string_clauseelement_dict = symbol("CD")
     """Visit a dictionary of string keys to :class:`_expression.ClauseElement`
@@ -380,8 +380,8 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)):
     """
 
     dp_table_hint_list = symbol("TH")
-    """Visit the ``_hints`` collection of a :class:`_expression.Select` object
-    .
+    """Visit the ``_hints`` collection of a :class:`_expression.Select`
+    object.
 
     """
 
@@ -400,17 +400,17 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)):
     """
 
     dp_dml_ordered_values = symbol("DML_OV")
-    """visit the values() ordered tuple list of an
+    """Visit the values() ordered tuple list of an
     :class:`_expression.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.
 
     """
 
     dp_dml_multi_values = symbol("DML_MV")
-    """visit the values() multi-valued list of dictionaries of an
+    """Visit the values() multi-valued list of dictionaries of an
     :class:`_expression.Insert` object.
 
     """
@@ -479,14 +479,14 @@ class ExternalTraversal(object):
                 return meth(obj, **kw)
 
     def iterate(self, obj):
-        """traverse the given expression structure, returning an iterator
+        """Traverse the given expression structure, returning an iterator
         of all elements.
 
         """
         return iterate(obj, self.__traverse_options__)
 
     def traverse(self, obj):
-        """traverse and visit the given expression structure."""
+        """Traverse and visit the given expression structure."""
 
         return traverse(obj, self.__traverse_options__, self._visitor_dict)
 
@@ -501,7 +501,7 @@ class ExternalTraversal(object):
 
     @property
     def visitor_iterator(self):
-        """iterate through this visitor and each 'chained' visitor."""
+        """Iterate through this visitor and each 'chained' visitor."""
 
         v = self
         while v:
@@ -509,9 +509,9 @@ class ExternalTraversal(object):
             v = getattr(v, "_next", None)
 
     def chain(self, visitor):
-        """'chain' an additional ClauseVisitor onto this ClauseVisitor.
+        """'Chain' an additional ClauseVisitor onto this ClauseVisitor.
 
-        the chained visitor will receive all visit events after this one.
+        The chained visitor will receive all visit events after this one.
 
         """
         tail = list(self.visitor_iterator)[-1]
@@ -537,7 +537,7 @@ class CloningExternalTraversal(ExternalTraversal):
         return [self.traverse(x) for x in list_]
 
     def traverse(self, obj):
-        """traverse and visit the given expression structure."""
+        """Traverse and visit the given expression structure."""
 
         return cloned_traverse(
             obj, self.__traverse_options__, self._visitor_dict
@@ -554,7 +554,7 @@ class ReplacingExternalTraversal(CloningExternalTraversal):
     """
 
     def replace(self, elem):
-        """receive pre-copied elements during a cloning traversal.
+        """Receive pre-copied elements during a cloning traversal.
 
         If the method returns a new element, the element is used
         instead of creating a simple copy of the element.  Traversal
@@ -563,7 +563,7 @@ class ReplacingExternalTraversal(CloningExternalTraversal):
         return None
 
     def traverse(self, obj):
-        """traverse and visit the given expression structure."""
+        """Traverse and visit the given expression structure."""
 
         def replace(elem):
             for v in self.visitor_iterator:
@@ -583,9 +583,9 @@ ReplacingCloningVisitor = ReplacingExternalTraversal
 
 
 def iterate(obj, opts=util.immutabledict()):
-    r"""traverse the given expression structure, returning an iterator.
+    r"""Traverse the given expression structure, returning an iterator.
 
-    traversal is configured to be breadth-first.
+    Traversal is configured to be breadth-first.
 
     The central API feature used by the :func:`.visitors.iterate`
     function is the
@@ -618,7 +618,7 @@ def iterate(obj, opts=util.immutabledict()):
 
 
 def traverse_using(iterator, obj, visitors):
-    """visit the given expression structure using the given iterator of
+    """Visit the given expression structure using the given iterator of
     objects.
 
     :func:`.visitors.traverse_using` is usually called internally as the result
@@ -650,7 +650,7 @@ def traverse_using(iterator, obj, visitors):
 
 
 def traverse(obj, opts, visitors):
-    """traverse and visit the given expression structure using the default
+    """Traverse and visit the given expression structure using the default
     iterator.
 
      e.g.::
@@ -683,7 +683,7 @@ def traverse(obj, opts, visitors):
 
 
 def cloned_traverse(obj, opts, visitors):
-    """clone the given expression structure, allowing modifications by
+    """Clone the given expression structure, allowing modifications by
     visitors.
 
     Traversal usage is the same as that of :func:`.visitors.traverse`.
@@ -738,14 +738,14 @@ def cloned_traverse(obj, opts, visitors):
 
 
 def replacement_traverse(obj, opts, replace):
-    """clone the given expression structure, allowing element
+    """Clone the given expression structure, allowing element
     replacement by a given replacement function.
 
     This function is very similar to the :func:`.visitors.cloned_traverse`
     function, except instead of being passed a dictionary of visitors, all
     elements are unconditionally passed into the given replace function.
     The replace function then has the option to return an entirely new object
-    which will replace the one given.  if it returns ``None``, then the object
+    which will replace the one given.  If it returns ``None``, then the object
     is kept in place.
 
     The difference in usage between :func:`.visitors.cloned_traverse` and