Merge "Enable zzzeeksphinx module prefixes"

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(