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

1 files changed, 27 insertions, 36 deletions

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