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 4d19251f4ea9475660ead02344092ab337c4fd58..fc2f524eb30671823ba55e82cbacebfe37ee1612 100644 (file)
--- 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 26016814b38b9e4d21f39fbf270e752d56098314..aef5b699036699d2cbfc2c60826d98d9ac370912 100644 (file)
--- 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 7436696a8f5ad08133b8fea5b97aa4a4eb4190db..cacfb8d84e74784b514cc196381f6a7bd41810dc 100644 (file)
--- 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 adfee1737f7854a46683f9b340b8c0e7136fe908..45fd26e89a2164c82e0e1d26f006525d63b66a52 100644 (file)
--- 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`
 
         """