pass through docs for 2.0 style

this change restores the orm/tutorial.rst and
core/tutorial.rst files, hidden from the index with
an update on the new tutorial.

Also started noting Query is legacy, as we will have
lots of docs to update for 2.0 style.

Change-Id: I4f98eeaaa0fd6e03b9976320b568975fe6d06ade

2 files changed, 12 insertions, 21 deletions

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index bd897211c..c987f6b16 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -101,9 +101,6 @@ class Query(
     :meth:`_query.Query.with_session`
     method.
 
-    For a full walk through of :class:`_query.Query` usage, see the
-    :ref:`ormtutorial_toplevel`.
-
     """
 
     # elements that are in Core and can be cached in the same way
@@ -2290,17 +2287,6 @@ class Query(
 
          .. note:: This flag is considered legacy.
 
-        .. seealso::
-
-            :ref:`ormtutorial_joins` in the ORM tutorial.
-
-            :ref:`inheritance_toplevel` for details on how
-            :meth:`_query.Query.join` is used for inheritance relationships.
-
-            :func:`_orm.join` - a standalone ORM-level join function,
-            used internally by :meth:`_query.Query.join`, which in previous
-            SQLAlchemy versions was the primary ORM-level joining interface.
-
         """
 
         aliased, from_joinpoint, isouter, full = (
@@ -2772,11 +2758,6 @@ class Query(
         appropriate to the entity class represented by this
         :class:`_query.Query`.
 
-        .. seealso::
-
-            :ref:`orm_tutorial_literal_sql` - usage examples in the
-            ORM tutorial
-
         """
         statement = coercions.expect(
             roles.SelectStatementRole, statement, apply_propagate_attrs=self
@@ -3117,8 +3098,6 @@ class Query(
 
                 :ref:`faq_query_deduplicating`
 
-                :ref:`orm_tutorial_query_returning`
-
         For fine grained control over specific columns to count, to skip the
         usage of a subquery or otherwise control of the FROM clause, or to use
         other aggregate functions, use :attr:`~sqlalchemy.sql.expression.func`
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 95d329ab0..8be5fbee7 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -2042,6 +2042,18 @@ class Session(_SessionClassMethods):
         """Return a new :class:`_query.Query` object corresponding to this
         :class:`_orm.Session`.
 
+        Note that the :class:`_query.Query` object is legacy as of
+        SQLAlchemy 2.0; the :func:`_sql.select` construct is now used
+        to construct ORM queries.
+
+        .. seealso::
+
+            :ref:`unified_tutorial`
+
+            :ref:`queryguide_toplevel`
+
+            :ref:`query_api_toplevel` - legacy API doc
+
         """
 
         return self._query_cls(entities, self, **kwargs)