Merge "Enable zzzeeksphinx module prefixes"

36 files changed, 314 insertions, 185 deletions

diff --git a/doc/build/changelog/changelog_07.rst b/doc/build/changelog/changelog_07.rst
index f921d2949..43ae2fe0d 100644
--- a/doc/build/changelog/changelog_07.rst
+++ b/doc/build/changelog/changelog_07.rst
@@ -2578,7 +2578,7 @@
 
       The behavior of =/!= when comparing a scalar select
       to a value will no longer produce IN/NOT IN as of 0.8;
-      this behavior is a little too heavy handed (use in_() if
+      this behavior is a little too heavy handed (use ``in_()`` if
       you want to emit IN) and now emits a deprecation warning.
       To get the 0.8 behavior immediately and remove the warning,
       a compiler recipe is given at
diff --git a/doc/build/changelog/changelog_08.rst b/doc/build/changelog/changelog_08.rst
index 90407b2b2..7e0994dfc 100644
--- a/doc/build/changelog/changelog_08.rst
+++ b/doc/build/changelog/changelog_08.rst
@@ -356,9 +356,9 @@
         :tickets: 2957
         :versions: 0.9.3
 
-        Fixed bug where :meth:`.in_()` would go into an endless loop if
-        erroneously passed a column expression whose comparator included
-        the ``__getitem__()`` method, such as a column that uses the
+        Fixed bug where :meth:`.ColumnOperators.in_()` would go into an endless
+        loop if erroneously passed a column expression whose comparator
+        included the ``__getitem__()`` method, such as a column that uses the
         :class:`.postgresql.ARRAY` type.
 
     .. change::
diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst
index 7f73fa9e4..195f0f498 100644
--- a/doc/build/changelog/changelog_10.rst
+++ b/doc/build/changelog/changelog_10.rst
@@ -1006,8 +1006,8 @@
         :tickets: 3459
 
         Added a :meth:`.ColumnElement.cast` method which performs the same
-        purpose as the standalone :func:`.cast` function.  Pull request
-        courtesy Sebastian Bank.
+        purpose as the standalone :func:`.expression.cast` function.  Pull
+        request courtesy Sebastian Bank.
 
     .. change::
         :tags: bug, engine
@@ -1181,7 +1181,7 @@
         Repaired the :class:`.ExcludeConstraint` construct to support common
         features that other objects like :class:`.Index` now do, that
         the column expression may be specified as an arbitrary SQL
-        expression such as :obj:`.cast` or :obj:`.text`.
+        expression such as :obj:`.expression.cast` or :obj:`.expression.text`.
 
     .. change::
         :tags: feature, postgresql
@@ -1206,14 +1206,13 @@
         :tags: bug, orm
         :tickets: 3448
 
-        Fixed an unexpected-use regression whereby custom :class:`.Comparator`
-        objects that made use of the ``__clause_element__()`` method and
-        returned an object that was an ORM-mapped
-        :class:`.InstrumentedAttribute` and not explicitly a
-        :class:`.ColumnElement` would fail to be correctly
-        handled when passed as an expression to :meth:`.Session.query`.
-        The logic in 0.9 happened to succeed on this, so this use case is now
-        supported.
+        Fixed an unexpected-use regression whereby custom
+        :class:`.types.TypeEngine.Comparator` objects that made use of the
+        ``__clause_element__()`` method and returned an object that was an
+        ORM-mapped :class:`.InstrumentedAttribute` and not explicitly a
+        :class:`.ColumnElement` would fail to be correctly handled when passed
+        as an expression to :meth:`.Session.query`. The logic in 0.9 happened
+        to succeed on this, so this use case is now supported.
 
     .. change::
         :tags: bug, sql
diff --git a/doc/build/changelog/changelog_12.rst b/doc/build/changelog/changelog_12.rst
index 4173cf969..e5c145642 100644
--- a/doc/build/changelog/changelog_12.rst
+++ b/doc/build/changelog/changelog_12.rst
@@ -878,15 +878,15 @@
     :released: May 28, 2018
 
     .. change::
-    	:tags: bug, orm
-    	:tickets: 4256
+      :tags: bug, orm
+      :tickets: 4256
 
-    	Fixed regression in 1.2.7 caused by :ticket:`4228`, which itself was fixing
-    	a 1.2-level regression, where the ``query_cls`` callable passed to a
-    	:class:`.Session` was assumed to be a subclass of :class:`.Query`  with
-    	class method availability, as opposed to an arbitrary callable.    In
-    	particular, the dogpile caching example illustrates ``query_cls`` as a
-    	function and not a :class:`.Query` subclass.
+      Fixed regression in 1.2.7 caused by :ticket:`4228`, which itself was fixing
+      a 1.2-level regression, where the ``query_cls`` callable passed to a
+      :class:`.Session` was assumed to be a subclass of :class:`.Query`  with
+      class method availability, as opposed to an arbitrary callable.    In
+      particular, the dogpile caching example illustrates ``query_cls`` as a
+      function and not a :class:`.Query` subclass.
 
     .. change::
         :tags: bug, engine
@@ -924,15 +924,15 @@
 
 
     .. change::
-    	:tags: bug, ext
-    	:tickets: 4247
+      :tags: bug, ext
+      :tickets: 4247
 
-    	The horizontal sharding extension now makes use of the identity token
-    	added to ORM identity keys as part of :ticket:`4137`, when an object
-    	refresh or column-based deferred load or unexpiration operation occurs.
-    	Since we know the "shard" that the object originated from, we make
-    	use of this value when refreshing, thereby avoiding queries against
-    	other shards that don't match this object's identity in any case.
+      The horizontal sharding extension now makes use of the identity token
+      added to ORM identity keys as part of :ticket:`4137`, when an object
+      refresh or column-based deferred load or unexpiration operation occurs.
+      Since we know the "shard" that the object originated from, we make
+      use of this value when refreshing, thereby avoiding queries against
+      other shards that don't match this object's identity in any case.
 
     .. change::
         :tags: bug, sql
@@ -1005,15 +1005,15 @@
         of these issues as part of issue :ticket:`4258`.
 
     .. change::
-    	:tags: bug, ext
-    	:tickets: 4266
+      :tags: bug, ext
+      :tickets: 4266
 
-    	Fixed a race condition which could occur if automap
-    	:meth:`.AutomapBase.prepare` were used within a multi-threaded context
-    	against other threads which  may call :func:`.configure_mappers` as a
-    	result of use of other mappers.  The unfinished mapping work of automap
-    	is particularly sensitive to being pulled in by a
-    	:func:`.configure_mappers` step leading to errors.
+      Fixed a race condition which could occur if automap
+      :meth:`.AutomapBase.prepare` were used within a multi-threaded context
+      against other threads which  may call :func:`.configure_mappers` as a
+      result of use of other mappers.  The unfinished mapping work of automap
+      is particularly sensitive to being pulled in by a
+      :func:`.configure_mappers` step leading to errors.
 
     .. change::
         :tags: bug, orm
@@ -1025,12 +1025,12 @@
         the post criteria feature is now used by the lazy loader.
 
     .. change::
-    	:tags: bug, tests
-    	:tickets: 4249
+      :tags: bug, tests
+      :tickets: 4249
 
-    	Fixed a bug in the test suite where if an external dialect returned
-    	``None`` for ``server_version_info``, the exclusion logic would raise an
-    	``AttributeError``.
+      Fixed a bug in the test suite where if an external dialect returned
+      ``None`` for ``server_version_info``, the exclusion logic would raise an
+      ``AttributeError``.
 
     .. change::
         :tags: bug, orm
@@ -1950,18 +1950,18 @@
         index implicitly added by Oracle onto the primary key columns.
 
     .. change::
-    	:tags: bug, orm
-    	:tickets: 4071
+      :tags: bug, orm
+      :tickets: 4071
 
-    	Removed the warnings that are emitted when the LRU caches employed
-    	by the mapper as well as loader strategies reach their threshold; the
-    	purpose of this warning was at first a guard against excess cache keys
-    	being generated but became basically a check on the "creating many
-    	engines" antipattern.   While this is still an antipattern, the presence
-    	of test suites which both create an engine per test as well as raise
-    	on all warnings will be an inconvenience; it should not be critical
-    	that such test suites change their architecture just for this warning
-    	(though engine-per-test suite is always better).
+      Removed the warnings that are emitted when the LRU caches employed
+      by the mapper as well as loader strategies reach their threshold; the
+      purpose of this warning was at first a guard against excess cache keys
+      being generated but became basically a check on the "creating many
+      engines" antipattern.   While this is still an antipattern, the presence
+      of test suites which both create an engine per test as well as raise
+      on all warnings will be an inconvenience; it should not be critical
+      that such test suites change their architecture just for this warning
+      (though engine-per-test suite is always better).
 
     .. change::
         :tags: bug, orm
@@ -2089,11 +2089,12 @@
         Internal refinements to the :class:`.Enum`, :class:`.Interval`, and
         :class:`.Boolean` types, which now extend a common mixin
         :class:`.Emulated` that indicates a type that provides Python-side
-        emulation of a DB native type, switching out to the DB native type when a
-        supporting backend is in use.   The PostgreSQL :class:`.INTERVAL` type
-        when used directly will now include the correct type coercion rules for
-        SQL expressions that also take effect for :class:`.sqltypes.Interval`
-        (such as adding a date to an interval yields a datetime).
+        emulation of a DB native type, switching out to the DB native type when
+        a supporting backend is in use.   The PostgreSQL
+        :class:`.postgresql.INTERVAL` type when used directly will now include
+        the correct type coercion rules for SQL expressions that also take
+        effect for :class:`.sqltypes.Interval` (such as adding a date to an
+        interval yields a datetime).
 
 
     .. change::
diff --git a/doc/build/changelog/migration_08.rst b/doc/build/changelog/migration_08.rst
index f8487d51d..b707a912c 100644
--- a/doc/build/changelog/migration_08.rst
+++ b/doc/build/changelog/migration_08.rst
@@ -413,7 +413,7 @@ and :meth:`.PropComparator.has`::
 
 .. seealso::
 
-    :ref:`of_type`
+    :ref:`inheritance_of_type`
 
 :ticket:`2438` :ticket:`1106`
 
@@ -960,7 +960,7 @@ when features such as :meth:`.MetaData.create_all` and :func:`.cast` is used::
 :ticket:`2276`
 
 "Prefixes" now supported for :func:`.update`, :func:`.delete`
--------------------------------------------------------------
+----------------------------------------------------------------------------
 
 Geared towards MySQL, a "prefix" can be rendered within any of
 these constructs.   E.g.::
diff --git a/doc/build/changelog/migration_09.rst b/doc/build/changelog/migration_09.rst
index 376e83236..df4a2c57f 100644
--- a/doc/build/changelog/migration_09.rst
+++ b/doc/build/changelog/migration_09.rst
@@ -83,7 +83,7 @@ accessor::
 .. _migration_2736:
 
 :meth:`.Query.select_from` no longer applies the clause to corresponding entities
----------------------------------------------------------------------------------
+-----------------------------------------------------------------------------------------------
 
 The :meth:`.Query.select_from` method has been popularized in recent versions
 as a means of controlling the first thing that a :class:`.Query` object
@@ -564,8 +564,9 @@ by that of most database documentation::
     -- 0.9 behavior
     x = :x_1 COLLATE en_EN
 
-The potentially backwards incompatible change arises if the :meth:`.collate`
-operator is being applied to the right-hand column, as follows::
+The potentially backwards incompatible change arises if the
+:meth:`.ColumnOperators.collate` operator is being applied to the right-hand
+column, as follows::
 
     print(column('x') == literal('somevalue').collate("en_EN"))
 
diff --git a/doc/build/changelog/migration_13.rst b/doc/build/changelog/migration_13.rst
index b749f5623..6f99bb708 100644
--- a/doc/build/changelog/migration_13.rst
+++ b/doc/build/changelog/migration_13.rst
@@ -1321,13 +1321,12 @@ SQL text from being rendered directly.
 "threadlocal" engine strategy deprecated
 -----------------------------------------
 
-The :ref:`"threadlocal" engine strategy <threadlocal_strategy>` was added
-around SQLAlchemy 0.2, as a solution to the problem that the standard way of
-operating in SQLAlchemy 0.1, which can be summed up as "threadlocal
-everything",  was found to be lacking. In retrospect, it seems fairly absurd
-that by SQLAlchemy's first releases which were in every regard "alpha", that
-there was concern that too many users had already settled on the existing API
-to simply change it.
+The "threadlocal engine strategy" was added around SQLAlchemy 0.2, as a
+solution to the problem that the standard way of operating in SQLAlchemy 0.1,
+which can be summed up as "threadlocal everything",  was found to be lacking.
+In retrospect, it seems fairly absurd that by SQLAlchemy's first releases which
+were in every regard "alpha", that there was concern that too many users had
+already settled on the existing API to simply change it.
 
 The original usage model for SQLAlchemy looked like this::
 
diff --git a/doc/build/changelog/migration_14.rst b/doc/build/changelog/migration_14.rst
index b35818075..a5a3f83d0 100644
--- a/doc/build/changelog/migration_14.rst
+++ b/doc/build/changelog/migration_14.rst
@@ -23,7 +23,7 @@ What's New in SQLAlchemy 1.4?
 Behavioral Changes - General
 ============================
 
-.. _change_change_deferred_construction:
+.. _change_deferred_construction:
 
 
 Many Core and ORM statement objects now perform much of their validation in the compile phase
diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst
index d9fc6c6c4..c712ab991 100644
--- a/doc/build/changelog/migration_20.rst
+++ b/doc/build/changelog/migration_20.rst
@@ -731,7 +731,7 @@ ORM Query Unified with Core Select
 
   Tenative overall, however there will almost definitely be
   architectural changes in :class:`.Query` that move it closer to
-  :meth:`.select`.
+  :func:`.select`.
 
   The ``session.query(<cls>)`` pattern itself will likely **not** be fully
   removed.   As this pattern is extremely prevalent and numerous within any
diff --git a/doc/build/conf.py b/doc/build/conf.py
index 805290a89..266b20e08 100644
--- a/doc/build/conf.py
+++ b/doc/build/conf.py
@@ -37,6 +37,7 @@ extensions = [
     "changelog",
     "sphinx_paramlinks",
 ]
+needs_extensions = {"zzzeeksphinx": "1.1.2"}
 
 # Add any paths that contain templates here, relative to this directory.
 # not sure why abspath() is needed here, some users
@@ -88,6 +89,9 @@ changelog_render_changeset = "http://www.sqlalchemy.org/trac/changeset/%s"
 
 exclude_patterns = ["build", "**/unreleased*/*"]
 
+# zzzeeksphinx makes these conversions when it is rendering the
+# docstrings classes, methods, and functions within the scope of
+# Sphinx autodoc
 autodocmods_convert_modname = {
     "sqlalchemy.sql.sqltypes": "sqlalchemy.types",
     "sqlalchemy.sql.type_api": "sqlalchemy.types",
@@ -97,8 +101,10 @@ autodocmods_convert_modname = {
     "sqlalchemy.sql.dml": "sqlalchemy.sql.expression",
     "sqlalchemy.sql.ddl": "sqlalchemy.schema",
     "sqlalchemy.sql.base": "sqlalchemy.sql.expression",
+    "sqlalchemy.event.base": "sqlalchemy.event",
     "sqlalchemy.engine.base": "sqlalchemy.engine",
     "sqlalchemy.engine.result": "sqlalchemy.engine",
+    "sqlalchemy.util._collections": "sqlalchemy.util",
 }
 
 autodocmods_convert_modname_w_class = {
@@ -106,6 +112,42 @@ autodocmods_convert_modname_w_class = {
     ("sqlalchemy.sql.base", "DialectKWArgs"): "sqlalchemy.sql.base",
 }
 
+# on the referencing side, a newer zzzeeksphinx extension
+# applies shorthand symbols to references so that we can have short
+# names that are still using absolute references.
+zzzeeksphinx_module_prefixes = {
+    "_sa": "sqlalchemy",
+    "_engine": "sqlalchemy.engine",
+    "_schema": "sqlalchemy.schema",
+    "_types": "sqlalchemy.types",
+    "_expression": "sqlalchemy.sql.expression",
+    "_functions": "sqlalchemy.sql.functions",
+    "_pool": "sqlalchemy.pool",
+    "_event": "sqlalchemy.event",
+    "_events": "sqlalchemy.events",
+    "_exc": "sqlalchemy.exc",
+    "_reflection": "sqlalchemy.engine.reflection",
+    "_orm": "sqlalchemy.orm",
+    "_query": "sqlalchemy.orm.query",
+    "_ormevent": "sqlalchemy.orm.event",
+    "_ormexc": "sqlalchemy.orm.exc",
+    "_baked": "sqlalchemy.ext.baked",
+    "_associationproxy": "sqlalchemy.ext.associationproxy",
+    "_automap": "sqlalchemy.ext.automap",
+    "_hybrid": "sqlalchemy.ext.hybrid",
+    "_compilerext": "sqlalchemy.ext.compiler",
+    "_mutable": "sqlalchemy.ext.mutable",
+    "_declarative": "sqlalchemy.ext.declarative",
+    "_future": "sqlalchemy.future",
+    "_futureorm": "sqlalchemy.future.orm",
+    "_postgresql": "sqlalchemy.dialects.postgresql",
+    "_mysql": "sqlalchemy.dialects.mysql",
+    "_mssql": "sqlalchemy.dialects.mssql",
+    "_oracle": "sqlalchemy.dialects.oracle",
+    "_sqlite": "sqlalchemy.dialects.sqlite",
+}
+
+
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
 
diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst
index 7c2793f34..2191dee6e 100644
--- a/doc/build/core/connections.rst
+++ b/doc/build/core/connections.rst
@@ -75,7 +75,7 @@ any transactional state or locks are removed, and the connection is ready for
 its next use.
 
 .. deprecated:: 2.0 The :class:`.ResultProxy` object is replaced in SQLAlchemy
-   2.0 with a newly refined object known as :class:`.Result`.
+   2.0 with a newly refined object known as :class:`.future.Result`.
 
 Our example above illustrated the execution of a textual SQL string, which
 should be invoked by using the :func:`.text` construct to indicate that
diff --git a/doc/build/core/dml.rst b/doc/build/core/dml.rst
index d83a52e7b..d116b67a5 100644
--- a/doc/build/core/dml.rst
+++ b/doc/build/core/dml.rst
@@ -16,19 +16,29 @@ constructs build on the intermediary :class:`.ValuesBase`.
 
 .. autoclass:: Delete
    :members:
-   :inherited-members:
+
+   .. automethod:: Delete.where
+
+   .. automethod:: Delete.returning
 
 .. autoclass:: Insert
    :members:
-   :inherited-members:
+
+   .. automethod:: Insert.values
+
+   .. automethod:: Insert.returning
 
 .. autoclass:: Update
-  :members:
-  :inherited-members:
+   :members:
+
+   .. automethod:: Update.returning
+
+   .. automethod:: Update.where
+
+   .. automethod:: Update.values
 
 .. autoclass:: sqlalchemy.sql.expression.UpdateBase
-  :members:
-  :inherited-members:
+   :members:
 
 .. autoclass:: sqlalchemy.sql.expression.ValuesBase
    :members:
diff --git a/doc/build/core/inspection.rst b/doc/build/core/inspection.rst
index 313b4d6e7..01343102d 100644
--- a/doc/build/core/inspection.rst
+++ b/doc/build/core/inspection.rst
@@ -5,7 +5,9 @@ Runtime Inspection API
 ======================
 
 .. automodule:: sqlalchemy.inspection
-    :members:
+
+.. autofunction:: sqlalchemy.inspect
+
 
 Available Inspection Targets
 ----------------------------
diff --git a/doc/build/core/selectable.rst b/doc/build/core/selectable.rst
index 4771222e8..2f69c0200 100644
--- a/doc/build/core/selectable.rst
+++ b/doc/build/core/selectable.rst
@@ -78,13 +78,16 @@ elements are themselves :class:`.ColumnElement` subclasses).
 
 .. autoclass:: Select
    :members:
-   :inherited-members:
+   :inherited-members:  ClauseElement
+   :exclude-members: memoized_attribute, memoized_instancemethod
 
 .. autoclass:: Selectable
    :members:
 
 .. autoclass:: SelectBase
    :members:
+   :inherited-members:  ClauseElement
+   :exclude-members: memoized_attribute, memoized_instancemethod
 
 .. autoclass:: Subquery
    :members:
diff --git a/doc/build/errors.rst b/doc/build/errors.rst
index ed5583b12..43e0b9fa4 100644
--- a/doc/build/errors.rst
+++ b/doc/build/errors.rst
@@ -489,7 +489,7 @@ Above, the ``cprop`` attribute is used inline before it has been mapped,
 however this ``cprop`` attribute is not a :class:`.Column`,
 it's a :class:`.ColumnProperty`, which is an interim object and therefore
 does not have the full functionality of either the :class:`.Column` object
-or the :class:`.InstrmentedAttribute` object that will be mapped onto the
+or the :class:`.InstrumentedAttribute` object that will be mapped onto the
 ``Bar`` class once the declarative process is complete.
 
 While the :class:`.ColumnProperty` does have a ``__clause_element__()`` method,
diff --git a/doc/build/faq/metadata_schema.rst b/doc/build/faq/metadata_schema.rst
index 2d1527294..94cbb1787 100644
--- a/doc/build/faq/metadata_schema.rst
+++ b/doc/build/faq/metadata_schema.rst
@@ -50,7 +50,7 @@ Does SQLAlchemy support ALTER TABLE, CREATE VIEW, CREATE TRIGGER, Schema Upgrade
 
 General ALTER support isn't present in SQLAlchemy directly.  For special DDL
 on an ad-hoc basis, the :class:`.DDL` and related constructs can be used.
-See :doc:`core/ddl` for a discussion on this subject.
+See :ref:`metadata_ddl_toplevel` for a discussion on this subject.
 
 A more comprehensive option is to use schema migration tools, such as Alembic
 or SQLAlchemy-Migrate; see :ref:`schema_migrations` for discussion on this.
diff --git a/doc/build/faq/performance.rst b/doc/build/faq/performance.rst
index c30e96abb..65d6cc460 100644
--- a/doc/build/faq/performance.rst
+++ b/doc/build/faq/performance.rst
@@ -212,7 +212,7 @@ the profiling output of this intentionally slow operation can be seen like this:
 that is, we see many expensive calls within the ``type_api`` system, and the actual
 time consuming thing is the ``time.sleep()`` call.
 
-Make sure to check the :doc:`Dialect documentation <dialects/index>`
+Make sure to check the :ref:`Dialect documentation <dialect_toplevel>`
 for notes on known performance tuning suggestions at this level, especially for
 databases like Oracle.  There may be systems related to ensuring numeric accuracy
 or string processing that may not be needed in all cases.
@@ -295,14 +295,14 @@ ORM as a first-class component.
 
 For the use case of fast bulk inserts, the
 SQL generation and execution system that the ORM builds on top of
-is part of the :doc:`Core <core/tutorial>`.  Using this system directly, we can produce an INSERT that
+is part of the :ref:`Core <sqlexpression_toplevel>`.  Using this system directly, we can produce an INSERT that
 is competitive with using the raw database API directly.
 
 .. note::
 
-    When using the psycopg2 dialect, consider making use of the
-    :ref:`batch execution helpers <psycopg2_batch_mode>` feature of psycopg2,
-    now supported directly by the SQLAlchemy psycopg2 dialect.
+    When using the psycopg2 dialect, consider making use of the :ref:`batch
+    execution helpers <psycopg2_executemany_mode>` feature of psycopg2, now
+    supported directly by the SQLAlchemy psycopg2 dialect.
 
 Alternatively, the SQLAlchemy ORM offers the :ref:`bulk_operations`
 suite of methods, which provide hooks into subsections of the unit of
diff --git a/doc/build/orm/extensions/declarative/inheritance.rst b/doc/build/orm/extensions/declarative/inheritance.rst
index f23410683..b98843816 100644
--- a/doc/build/orm/extensions/declarative/inheritance.rst
+++ b/doc/build/orm/extensions/declarative/inheritance.rst
@@ -248,4 +248,3 @@ on concrete inheritance for details.
 
     :ref:`concrete_inheritance`
 
-    :ref:`inheritance_concrete_helpers`
diff --git a/doc/build/orm/join_conditions.rst b/doc/build/orm/join_conditions.rst
index a317c6ecc..68a2949ff 100644
--- a/doc/build/orm/join_conditions.rst
+++ b/doc/build/orm/join_conditions.rst
@@ -700,6 +700,8 @@ complexity is kept within the middle.
    sometimes ways to make relationships like the above writable, this is
    generally complicated and error prone.
 
+.. _relationship_non_primary_mapper:
+
 .. _relationship_aliased_class:
 
 Relationship to Aliased Class
diff --git a/doc/build/orm/mapping_api.rst b/doc/build/orm/mapping_api.rst
index 99e0ba52d..250bd26a4 100644
--- a/doc/build/orm/mapping_api.rst
+++ b/doc/build/orm/mapping_api.rst
@@ -15,8 +15,8 @@ Class Mapping API
 
 .. autofunction:: sqlalchemy.orm.util.identity_key
 
-.. autofunction:: sqlalchemy.orm.util.polymorphic_union
+.. autofunction:: polymorphic_union
 
-.. autoclass:: sqlalchemy.orm.mapper.Mapper
+.. autoclass:: Mapper
    :members:
 
diff --git a/doc/build/orm/nonstandard_mappings.rst b/doc/build/orm/nonstandard_mappings.rst
index 7516d1b54..522359854 100644
--- a/doc/build/orm/nonstandard_mappings.rst
+++ b/doc/build/orm/nonstandard_mappings.rst
@@ -157,35 +157,21 @@ Multiple Mappers for One Class
 ==============================
 
 In modern SQLAlchemy, a particular class is mapped by only one so-called
-**primary** mapper at a time.   This mapper is involved in three main
-areas of functionality: querying, persistence, and instrumentation of the
-mapped class.   The rationale of the primary mapper relates to the fact
-that the :func:`.mapper` modifies the class itself, not only
-persisting it towards a particular :class:`.Table`, but also :term:`instrumenting`
-attributes upon the class which are structured specifically according to the
-table metadata.   It's not possible for more than one mapper
-to be associated with a class in equal measure, since only one mapper can
-actually instrument the class.
-
-However, there is a class of mapper known as the **non primary** mapper
-which allows additional mappers to be associated with a class, but with
-a limited scope of use.   This scope typically applies to
-being able to load rows from an alternate table or selectable unit, but
-still producing classes which are ultimately persisted using the primary
-mapping.    The non-primary mapper is created using the classical style
-of mapping against a class that is already mapped with a primary mapper,
-and involves the use of the :paramref:`~sqlalchemy.orm.mapper.non_primary`
-flag.
-
-The non primary mapper is of very limited use in modern SQLAlchemy, as the
-task of being able to load classes from subqueries or other compound statements
-can be now accomplished using the :class:`.Query` object directly.
-
-There is really only one use case for the non-primary mapper, which is that
-we wish to build a :func:`.relationship` to such a mapper; this is useful
-in the rare and advanced case that our relationship is attempting to join two
-classes together using many tables and/or joins in between.  An example of this
-pattern is at :ref:`relationship_non_primary_mapper`.
+**primary** mapper at a time.   This mapper is involved in three main areas of
+functionality: querying, persistence, and instrumentation of the mapped class.
+The rationale of the primary mapper relates to the fact that the
+:func:`.mapper` modifies the class itself, not only persisting it towards a
+particular :class:`.Table`, but also :term:`instrumenting` attributes upon the
+class which are structured specifically according to the table metadata.   It's
+not possible for more than one mapper to be associated with a class in equal
+measure, since only one mapper can actually instrument the class.
+
+The concept of a "non-primary" mapper had existed for many versions of
+SQLAlchemy however as of version 1.3 this feature is deprecated.   The
+one case where such a non-primary mapper is useful is when constructing
+a relationship to a class against an alternative selectable.   This
+use case is now suited using the :class:`.aliased` construct and is described
+at :ref:`relationship_aliased_class`.
 
 As far as the use case of a class that can actually be fully persisted
 to different tables under different scenarios, very early versions of
diff --git a/doc/build/orm/session_state_management.rst b/doc/build/orm/session_state_management.rst
index 2730bb8b2..8b4d7a572 100644
--- a/doc/build/orm/session_state_management.rst
+++ b/doc/build/orm/session_state_management.rst
@@ -543,8 +543,8 @@ or loaded with :meth:`~.Session.refresh` varies based on several factors, includ
   expired column-based attributes being accessed.
 
 * Regarding relationships, :meth:`~.Session.refresh` is more restrictive than
-  :meth:`~.Session.expire` with regards to attributes that aren't column-mapped.
-  Calling :meth:`.refresh` and passing a list of names that only includes
+  :meth:`.Session.expire` with regards to attributes that aren't column-mapped.
+  Calling :meth:`.Session.refresh` and passing a list of names that only includes
   relationship-mapped attributes will actually raise an error.
   In any case, non-eager-loading :func:`.relationship` attributes will not be
   included in any refresh operation.
@@ -620,7 +620,7 @@ The second bullet has the important caveat that "it is also known that the isola
 allow this data to be visible."  This means that it cannot be assumed that an
 UPDATE that happened on another database connection will yet be visible here
 locally; in many cases, it will not.  This is why if one wishes to use
-:meth:`.expire` or :meth:`.refresh` in order to view data between ongoing
+:meth:`.Session.expire` or :meth:`.Session.refresh` in order to view data between ongoing
 transactions, an understanding of the isolation behavior in effect is essential.
 
 .. seealso::
diff --git a/doc/build/replacments/fix_xref_state.txt b/doc/build/replacments/fix_xref_state.txt
new file mode 100644
index 000000000..380657df2
--- /dev/null
+++ b/doc/build/replacments/fix_xref_state.txt
@@ -0,0 +1,93 @@
+.MetaData _schema.MetaData
+.ForeignKey _schema.ForeignKey
+.ForeignKeyConstraint _schema.ForeignKeyConstraint
+.PoolEvents _events.PoolEvents
+.DisconnectionError _exc.DisconnectionError
+.SADeprecationWarning _exc.SADeprecationWarning
+.Engine _engine.Engine
+.Pool _pool.Pool
+.future _future
+.inspect _sa.inspect
+.Inspector _reflection.Inspector
+.orm _orm
+.Mapper _orm.Mapper
+.engine _engine
+.JSON _types.JSON
+.postgresql _postgresql
+.types _types
+._mysql _mysql
+.sqlite _sqlite
+.array_agg _functions.array_agg
+.TIMESTAMP _types.TIMESTAMP
+.JSONB _postgresql.JSONB
+.ARRAY _types.ARRAY
+.mssql _mssql
+.sqltypes _types
+.functions _functions
+.INTERVAL _postgresql.INTERVAL
+.INTERVAL _oracle.INTERVAL
+.oracle _oracle
+.NCHAR _types.NCHAR
+.Query _query.Query
+.relationship _orm.relationship
+.FromClause _expression.FromClause
+.join _expression.join
+.SelectBase _expression.SelectBase
+.Load _orm.Load
+.joinedload _orm.joinedload
+.sql _expression
+.sql.expression _expression
+.INTEGER _types.INTEGER
+.VARBINARY _types.VARBINARY
+.joinedload_all _orm.joinedload_all
+.Insert _expression.Insert
+.Update _expression.Update
+.Delete _expression.Delete
+.insert _expression.insert
+.update _expression.update
+.delete _expression.delete
+.select _expression.select
+.expression _expression
+.future _future.Subquery _expression.Subquery
+.Select _expression.Select
+.ReturnsRows _expression.ReturnsRows
+.ColumnCollection _expression.ColumnCollection
+.ColumnElement _expression.ColumnElement
+.Selectable expression.Selectable
+.Lateral _expression.Lateral
+.HasPrefixes _expression.HasPrefixes
+.prefix_with _expression.HasPrefixes.prefix_with
+.ClauseElement _expression.ClauseElement
+.HasSuffixes _expression.HasSuffixes
+.suffix_with _expression.HasSuffixes.suffix_with
+.Table _schema.Table
+.Join _expression.Join
+.Alias _expression.Alias
+.TableSample _expression.TableSample
+.CTE _expression.CTE
+.HasCte _expression.HasCTE
+.HasCTE _expression.HasCTE
+.CompoundSelect _selectable.CompoundSelect
+.TextualSelect _expression.TextualSelect
+.TableClause _expression.TableClause
+.schema _schema
+.Values _expression.Values
+.column _expression.column
+.GenerativeSelect _expression.GenerativeSelect
+.Column _schema.Column
+.union _expression.union
+.union_all _expression.union_all
+.intersect _expression.intersect
+.intersect_all _expression.intersect_all
+.except _expression.except
+.except_all _expression.except_all
+.Text _expression.TextClause
+.text _expression.text
+.literal_column _expression.literal_column
+.Connection _engine.Connection
+.Engine _engine.Engine
+.apply_labels _expression.Select.apply_labels
+.BooleanClauseList _expression.BooleanClauseList
+.ScalarSelect _expression.ScalarSelect
+.Exists _expression.Exists
+.TextClause _expression.TextClause
diff --git a/lib/sqlalchemy/dialects/mssql/base.py b/lib/sqlalchemy/dialects/mssql/base.py
index a7086259b..43f3aeb04 100644
--- a/lib/sqlalchemy/dialects/mssql/base.py
+++ b/lib/sqlalchemy/dialects/mssql/base.py
@@ -391,9 +391,10 @@ behavior of this flag is as follows:
 
 * Complete control over whether the "old" or "new" types are rendered is
   available in all SQLAlchemy versions by using the UPPERCASE type objects
-  instead: :class:`.NVARCHAR`, :class:`.VARCHAR`, :class:`.types.VARBINARY`,
-  :class:`.TEXT`, :class:`.mssql.NTEXT`, :class:`.mssql.IMAGE` will always
-  remain fixed and always output exactly that type.
+  instead: :class:`.types.NVARCHAR`, :class:`.types.VARCHAR`,
+  :class:`.types.VARBINARY`, :class:`.types.TEXT`, :class:`.mssql.NTEXT`,
+  :class:`.mssql.IMAGE` will always remain fixed and always output exactly that
+  type.
 
 .. versionadded:: 1.0.0
 
diff --git a/lib/sqlalchemy/dialects/postgresql/psycopg2.py b/lib/sqlalchemy/dialects/postgresql/psycopg2.py
index cf521f06f..89a63fd47 100644
--- a/lib/sqlalchemy/dialects/postgresql/psycopg2.py
+++ b/lib/sqlalchemy/dialects/postgresql/psycopg2.py
@@ -140,6 +140,8 @@ The following DBAPI-specific options are respected when used with
   .. versionchanged:: 1.4  The ``max_row_buffer`` size can now be greater than
      1000, and the buffer will grow to that size.
 
+.. _psycopg2_batch_mode:
+
 .. _psycopg2_executemany_mode:
 
 Psycopg2 Fast Execution Helpers
diff --git a/lib/sqlalchemy/dialects/sqlite/pysqlite.py b/lib/sqlalchemy/dialects/sqlite/pysqlite.py
index 807f9488d..72bbd0177 100644
--- a/lib/sqlalchemy/dialects/sqlite/pysqlite.py
+++ b/lib/sqlalchemy/dialects/sqlite/pysqlite.py
@@ -325,7 +325,7 @@ ourselves. This is achieved using two event listeners::
         conn.exec_driver_sql("BEGIN")
 
 .. warning:: When using the above recipe, it is advised to not use the
-   :paramref:`.execution_options.isolation_level` setting on
+   :paramref:`.Connection.execution_options.isolation_level` setting on
    :class:`.Connection` and :func:`.create_engine` with the SQLite driver,
    as this function necessarily will also alter the ".isolation_level" setting.
 
diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py
index 3d50b0828..2831f5e7d 100644
--- a/lib/sqlalchemy/engine/create.py
+++ b/lib/sqlalchemy/engine/create.py
@@ -610,7 +610,7 @@ def engine_from_config(configuration, prefix="sqlalchemy.", **kwargs):
     :param configuration: A dictionary (typically produced from a config file,
         but this is not a requirement).  Items whose keys start with the value
         of 'prefix' will have that prefix stripped, and will then be passed to
-        :ref:`create_engine`.
+        :func:`.create_engine`.
 
     :param prefix: Prefix to match and then strip from keys
         in 'configuration'.
diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py
index ba998aff0..be44f67e7 100644
--- a/lib/sqlalchemy/engine/result.py
+++ b/lib/sqlalchemy/engine/result.py
@@ -1551,7 +1551,7 @@ class ResultProxy(BaseResult):
                 yield row
 
     def close(self):
-        """Close this ResultProxy.
+        """Close this :class:`.ResultProxy`.
 
         This closes out the underlying DBAPI cursor corresponding
         to the statement execution, if one is still present.  Note that the
@@ -1567,7 +1567,7 @@ class ResultProxy(BaseResult):
 
         .. deprecated:: 2.0 "connectionless" execution is deprecated and will
            be removed in version 2.0.   Version 2.0 will feature the
-           :class:`.Result` object that will no longer affect the status
+           :class:`.future.Result` object that will no longer affect the status
            of the originating connection in any case.
 
         After this method is called, it is no longer valid to call upon
diff --git a/lib/sqlalchemy/ext/associationproxy.py b/lib/sqlalchemy/ext/associationproxy.py
index f00b642db..599bf966d 100644
--- a/lib/sqlalchemy/ext/associationproxy.py
+++ b/lib/sqlalchemy/ext/associationproxy.py
@@ -81,7 +81,7 @@ def association_proxy(target_collection, attr, **kw):
 
 
 ASSOCIATION_PROXY = util.symbol("ASSOCIATION_PROXY")
-"""Symbol indicating an :class:`InspectionAttr` that's
+"""Symbol indicating an :class:`.InspectionAttr` that's
     of type :class:`.AssociationProxy`.
 
    Is assigned to the :attr:`.InspectionAttr.extension_type`
diff --git a/lib/sqlalchemy/ext/declarative/api.py b/lib/sqlalchemy/ext/declarative/api.py
index b1574339d..825c1d3f3 100644
--- a/lib/sqlalchemy/ext/declarative/api.py
+++ b/lib/sqlalchemy/ext/declarative/api.py
@@ -442,8 +442,6 @@ class ConcreteBase(object):
 
         :ref:`concrete_inheritance`
 
-        :ref:`inheritance_concrete_helpers`
-
 
     """
 
@@ -582,8 +580,6 @@ class AbstractConcreteBase(ConcreteBase):
 
         :ref:`concrete_inheritance`
 
-        :ref:`inheritance_concrete_helpers`
-
     """
 
     __no_table__ = True
diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 029a28c68..53118c573 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -239,7 +239,7 @@ defaultload = strategy_options.defaultload._unbound_fn
 selectin_polymorphic = strategy_options.selectin_polymorphic._unbound_fn
 
 
-@_sa_util.deprecated_20("relation", "Please use :func:`joinedload`.")
+@_sa_util.deprecated_20("eagerload", "Please use :func:`_orm.joinedload`.")
 def eagerload(*args, **kwargs):
     """A synonym for :func:`joinedload()`."""
     return joinedload(*args, **kwargs)
diff --git a/lib/sqlalchemy/orm/attributes.py b/lib/sqlalchemy/orm/attributes.py
index 2bacb25b0..82979b188 100644
--- a/lib/sqlalchemy/orm/attributes.py
+++ b/lib/sqlalchemy/orm/attributes.py
@@ -446,10 +446,10 @@ class Event(object):
 
     .. versionadded:: 0.9.0
 
-    :var impl: The :class:`.AttributeImpl` which is the current event
+    :attribute impl: The :class:`.AttributeImpl` which is the current event
      initiator.
 
-    :var op: The symbol :attr:`.OP_APPEND`, :attr:`.OP_REMOVE`,
+    :attribute op: The symbol :attr:`.OP_APPEND`, :attr:`.OP_REMOVE`,
      :attr:`.OP_REPLACE`, or :attr:`.OP_BULK_REPLACE`, indicating the
      source operation.
 
diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py
index 1fe51514e..6475f79de 100644
--- a/lib/sqlalchemy/orm/strategy_options.py
+++ b/lib/sqlalchemy/orm/strategy_options.py
@@ -982,9 +982,9 @@ class loader_option(object):
         self._unbound_fn = fn
         fn_doc = self.fn.__doc__
         self.fn.__doc__ = """Produce a new :class:`.Load` object with the
-:func:`.orm.%(name)s` option applied.
+:func:`_orm.%(name)s` option applied.
 
-See :func:`.orm.%(name)s` for usage examples.
+See :func:`_orm.%(name)s` for usage examples.
 
 """ % {
             "name": self.name
@@ -994,13 +994,14 @@ See :func:`.orm.%(name)s` for usage examples.
         return self
 
     def _add_unbound_all_fn(self, fn):
-        fn.__doc__ = """Produce a standalone "all" option for :func:`.orm.%(name)s`.
+        fn.__doc__ = """Produce a standalone "all" option for
+:func:`_orm.%(name)s`.
 
 .. deprecated:: 0.9
 
-    The :func:`.%(name)s_all` function is deprecated, and will be removed
-    in a future release.  Please use method chaining with :func:`.%(name)s`
-    instead, as in::
+    The :func:`_orm.%(name)s_all` function is deprecated, and will be removed
+    in a future release.  Please use method chaining with
+    :func:`_orm.%(name)s` instead, as in::
 
         session.query(MyClass).options(
             %(name)s("someattribute").%(name)s("anotherattribute")
@@ -1751,7 +1752,7 @@ def selectin_polymorphic(loadopt, classes):
 
     .. seealso::
 
-        :ref:`inheritance_polymorphic_load`
+        :ref:`polymorphic_selectin`
 
     """
     loadopt.set_class_strategy(
diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py
index cbcf54d1c..1ac3acd8a 100644
--- a/lib/sqlalchemy/sql/dml.py
+++ b/lib/sqlalchemy/sql/dml.py
@@ -200,47 +200,47 @@ class UpdateBase(
 
         param_to_method_lookup = dict(
             whereclause=(
-                "The :paramref:`.%(func)s.whereclause` parameter "
+                "The :paramref:`%(func)s.whereclause` parameter "
                 "will be removed "
                 "in SQLAlchemy 2.0.  Please refer to the "
                 ":meth:`.%(classname)s.where` method."
             ),
             values=(
-                "The :paramref:`.%(func)s.values` parameter will be removed "
+                "The :paramref:`%(func)s.values` parameter will be removed "
                 "in SQLAlchemy 2.0.  Please refer to the "
-                ":meth:`.%(classname)s.values` method."
+                ":meth:`%(classname)s.values` method."
             ),
             bind=(
-                "The :paramref:`.%(func)s.bind` parameter will be removed in "
+                "The :paramref:`%(func)s.bind` parameter will be removed in "
                 "SQLAlchemy 2.0.  Please use explicit connection execution."
             ),
             inline=(
-                "The :paramref:`.%(func)s.inline` parameter will be "
+                "The :paramref:`%(func)s.inline` parameter will be "
                 "removed in "
                 "SQLAlchemy 2.0.  Please use the "
-                ":meth:`.%(classname)s.inline` method."
+                ":meth:`%(classname)s.inline` method."
             ),
             prefixes=(
-                "The :paramref:`.%(func)s.prefixes parameter will be "
+                "The :paramref:`%(func)s.prefixes parameter will be "
                 "removed in "
                 "SQLAlchemy 2.0.  Please use the "
-                ":meth:`.%(classname)s.prefix_with` "
+                ":meth:`%(classname)s.prefix_with` "
                 "method."
             ),
             return_defaults=(
-                "The :paramref:`.%(func)s.return_defaults` parameter will be "
+                "The :paramref:`%(func)s.return_defaults` parameter will be "
                 "removed in SQLAlchemy 2.0.  Please use the "
-                ":meth:`.%(classname)s.return_defaults` method."
+                ":meth:`%(classname)s.return_defaults` method."
             ),
             returning=(
-                "The :paramref:`.%(func)s.returning` parameter will be "
+                "The :paramref:`%(func)s.returning` parameter will be "
                 "removed in SQLAlchemy 2.0.  Please use the "
-                ":meth:`.%(classname)s.returning`` method."
+                ":meth:`%(classname)s.returning`` method."
             ),
             preserve_parameter_order=(
                 "The :paramref:`%(func)s.preserve_parameter_order` parameter "
                 "will be removed in SQLAlchemy 2.0.   Use the "
-                ":meth:`.%(classname)s.ordered_values` method with a list "
+                ":meth:`%(classname)s.ordered_values` method with a list "
                 "of tuples. "
             ),
         )
@@ -250,7 +250,10 @@ class UpdateBase(
                 name: (
                     "2.0",
                     param_to_method_lookup[name]
-                    % {"func": fn_name, "classname": clsname},
+                    % {
+                        "func": "_expression.%s" % fn_name,
+                        "classname": "_expression.%s" % clsname,
+                    },
                 )
                 for name in names
             }
@@ -546,25 +549,13 @@ class ValuesBase(UpdateBase):
               callable is invoked for each row.   See :ref:`bug_3288`
               for other details.
 
-         The :class:`.Update` construct supports a special form which is a
-         list of 2-tuples, which when provided must be passed in conjunction
-         with the
-         :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order`
-         parameter.
-         This form causes the UPDATE statement to render the SET clauses
-         using the order of parameters given to :meth:`.Update.values`, rather
-         than the ordering of columns given in the :class:`.Table`.
-
-           .. versionadded:: 1.0.10 - added support for parameter-ordered
-              UPDATE statements via the
-              :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order`
-              flag.
+          The UPDATE construct also supports rendering the SET parameters
+          in a specific order.  For this feature refer to the
+          :meth:`.Update.ordered_values` method.
 
            .. seealso::
 
-              :ref:`updates_order_parameters` - full example of the
-              :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order`
-              flag
+              :meth:`.Update.ordered_values`
 
         .. seealso::
 
@@ -1064,8 +1055,8 @@ class Update(DMLWhereBase, ValuesBase):
 
           .. seealso::
 
-            :ref:`updates_order_parameters` - full example of the
-            :paramref:`~.update.preserve_parameter_order` flag
+            :ref:`updates_order_parameters` - illustrates the
+            :meth:`.Update.ordered_values` method.
 
         If both ``values`` and compile-time bind parameters are present, the
         compile-time bind parameters override the information specified
@@ -1089,7 +1080,8 @@ class Update(DMLWhereBase, ValuesBase):
           etc.
 
         when combining :func:`~.sql.expression.select` constructs within the
-        values clause of an :func:`.update` construct, the subquery represented
+        values clause of an :func:`.update`
+        construct, the subquery represented
         by the :func:`~.sql.expression.select` should be *correlated* to the
         parent table, that is, providing criterion which links the table inside
         the subquery to the outer table being updated::
@@ -1135,8 +1127,7 @@ class Update(DMLWhereBase, ValuesBase):
         .. seealso::
 
            :ref:`updates_order_parameters` - full example of the
-           :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order`
-           flag
+           :meth:`.Update.ordered_values` method.
 
         .. versionchanged:: 1.4 The :meth:`.Update.ordered_values` method
            supersedes the :paramref:`.update.preserve_parameter_order`
@@ -1219,7 +1210,7 @@ class Delete(DMLWhereBase, UpdateBase):
         prefixes=None,
         **dialect_kw
     ):
-        """Construct :class:`.Delete` object.
+        r"""Construct :class:`.Delete` object.
 
         Similar functionality is available via the
         :meth:`~.TableClause.delete` method on
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index 9c593ea5d..08a237636 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -3424,7 +3424,7 @@ class Select(
 
         All arguments which accept :class:`.ClauseElement` arguments also
         accept string arguments, which will be converted as appropriate into
-        either :func:`text()` or :func:`literal_column()` constructs.
+        either :func:`.text()` or :func:`.literal_column()` constructs.
 
         .. seealso::
 
diff --git a/lib/sqlalchemy/util/deprecations.py b/lib/sqlalchemy/util/deprecations.py
index 4bc37bf04..ad734a1c3 100644
--- a/lib/sqlalchemy/util/deprecations.py
+++ b/lib/sqlalchemy/util/deprecations.py
@@ -21,6 +21,7 @@ from .. import exc
 def _warn_with_version(msg, version, type_, stacklevel):
     warn = type_(msg)
     warn.deprecated_since = version
+
     warnings.warn(warn, stacklevel=stacklevel + 1)
 
 
@@ -219,7 +220,7 @@ def _sanitize_restructured_text(text):
         return name
 
     text = re.sub(r":ref:`(.+) <.*>`", lambda m: '"%s"' % m.group(1), text)
-    return re.sub(r"\:(\w+)\:`~?\.?(.+?)`", repl, text)
+    return re.sub(r"\:(\w+)\:`~?(?:_\w+)?\.?(.+?)`", repl, text)
 
 
 def _decorate_cls_with_warning(