Enable zzzeeksphinx module prefixes

zzzeeksphinx 1.1.2 in git can now convert short
prefix names in a configured lookup to fully qualified module
names, so that
we can have succinct and portable pyrefs
that still resolve absolutely.
It also includes a formatter that will format all pyrefs
in a fully consistent way regardless of the package path,
by unconditionally removing all package tokens but always
leaving class names in place including for methods, which
means we no longer have to deal with tildes in pyrefs.

The most immediate goal of the absolute prefixes is
that we have lots of
"ambiguous" names that appear in muliple places, like select(),
ARRAY, ENUM etc.   With the incoming future packages there
is going to be lots of name overlap so it is necessary
that all names eventually use absolute package paths
when Sphinx receives them.

In multiple stages, pyrefs will be converted using the
zzzeeksphinx tools/fix_xrefs.py tool so that doclinks can
be made absolute using symbolic prefixes.

For this review, the actual search and replace of symbols
is not performed, instead some general cleanup to prepare
the docs as well as a lookup file used by the tool
to do the conversion.   this relatively small patch will
be backported
with appropriate changes to 1.3, 1.2, 1.1 and the tool
can then be run on each branch individually.  We are shooting
for almost no warnings at all for master (still a handful
I can't figure out which don't seem to have any impact)
, very few for 1.3,
and for 1.2 / 1.1 we hope for a significant reduction
in warnings.

Overall for all versions pyrefs should
always point to the correct target, if they are in fact
hyperlinked.  it's better for a ref to go nowhere and
be plain text than go to the wrong thing.  Right now,
hundreds of API links are pointing to the wrong thing
as they are ambiguous names such as refresh(), insert(),
update(), select(), join(), JSON etc. and Sphinx sends these all
to essesntially random destinations among as many as five
or six possible choices per symbol.  A shorthand system
that allows us to use absolute refs without having
to type out a full blown absoulte module is the only
way this is going to work, and we should ultimately
seek to abandon any use of prefix dot for lookups.  Everything
should be on an underscore token so at the very least the module
spaces can be reorganized without having to search and replace
the entire documentation every time.

Change-Id: I484a7329034af275fcdb322b62b6255dfeea9151

13 files changed, 52 insertions, 60 deletions

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(