From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Mon, 19 Apr 2021 15:45:09 +0000 (-0400)
Subject: add some cross-linking for orderby/groupby docs + label examples
X-Git-Tag: rel_1_4_10~8
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=a58c99977eafc5f69a3e37f9ddcc328698e7fe1e;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

add some cross-linking for orderby/groupby docs + label examples

Change-Id: I34d4958ded8ec95e439ee47fdcb600f357cf7ae3
References: #6324
---

diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst
index 4d19251f4e..fc2f524eb3 100644
--- a/doc/build/core/tutorial.rst
+++ b/doc/build/core/tutorial.rst
@@ -1217,6 +1217,8 @@ be quoted:
     [...] (', ', '%@aol.com', '%@msn.com')
     {stop}[(u'Wendy Williams, wendy@aol.com',)]
 
+.. _sqlexpression_order_by_label:
+
 Ordering or Grouping by a Label
 -------------------------------
 
@@ -2242,6 +2244,9 @@ This is provided via the :meth:`_expression.SelectBase.group_by` method:
     [...] ()
     {stop}[(u'jack', 2), (u'wendy', 2)]
 
+See also :ref:`sqlexpression_order_by_label` for an important technique
+of ordering or grouping by a string column name.
+
 HAVING can be used to filter results on an aggregate value, after GROUP BY has
 been applied.  It's available here via the :meth:`_expression.Select.having`
 method:
diff --git a/doc/build/tutorial/data.rst b/doc/build/tutorial/data.rst
index 26016814b3..aef5b69903 100644
--- a/doc/build/tutorial/data.rst
+++ b/doc/build/tutorial/data.rst
@@ -765,6 +765,8 @@ using ``.join(..., isouter=True)``.
     SQL also has a "RIGHT OUTER JOIN".  SQLAlchemy doesn't render this directly;
     instead, reverse the order of the tables and use "LEFT OUTER JOIN".
 
+.. _tutorial_order_by:
+
 ORDER BY
 ^^^^^^^^^
 
@@ -845,6 +847,8 @@ than one address:
     [('sandy', 2)]
     {opensql}ROLLBACK{stop}
 
+.. _tutorial_order_by_label:
+
 Ordering or Grouping by a Label
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 7436696a8f..cacfb8d84e 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1753,6 +1753,15 @@ class Query(
         All existing ORDER BY settings can be suppressed by  passing
         ``None``.
 
+        .. seealso::
+
+            These sections describe ORDER BY in terms of :term:`2.0 style`
+            invocation but apply to :class:`_orm.Query` as well:
+
+            :ref:`tutorial_order_by` - in the :ref:`unified_tutorial`
+
+            :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial`
+
         """
 
         if len(clauses) == 1 and (clauses[0] is None or clauses[0] is False):
@@ -1786,8 +1795,15 @@ class Query(
         passing ``None`` - this will suppress any GROUP BY configured
         on mappers as well.
 
-        .. versionadded:: 1.1 GROUP BY can be cancelled by passing
-           ``None``, in the same way as ORDER BY.
+        .. seealso::
+
+            These sections describe GROUP BY in terms of :term:`2.0 style`
+            invocation but apply to :class:`_orm.Query` as well:
+
+            :ref:`tutorial_group_by_w_aggregates` - in the
+            :ref:`unified_tutorial`
+
+            :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial`
 
         """
 
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index adfee1737f..45fd26e89a 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -3599,7 +3599,9 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
 
         .. seealso::
 
-            :ref:`core_tutorial_ordering`
+            :ref:`tutorial_order_by` - in the :ref:`unified_tutorial`
+
+            :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial`
 
         """
 
@@ -3627,7 +3629,10 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
 
         .. seealso::
 
-            :ref:`core_tutorial_ordering`
+            :ref:`tutorial_group_by_w_aggregates` - in the
+            :ref:`unified_tutorial`
+
+            :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial`
 
         """