additional consistency for ORM/Core in tutorial

* Make sure we have blue borders for all sections
* rewrite "blue border" text, refer to textual means of determining
  subject matter for a section; "blue borders" are not a primary
  source of information
* Add some more intro text that was missing

Change-Id: I4d599e13d23bad8bb3c199a11afb53e3e9100c59
References: #9450
(cherry picked from commit 8d5986fafd8360ddfe3992bd56602d5a52a23392)

diff --git a/doc/build/tutorial/data.rst b/doc/build/tutorial/data.rst
index 1d5dde7b847d24887b71614edfde87ee7a165c83..3242710a928dc4feaba8d5a0ede615bf6052406c 100644 (file)
--- a/doc/build/tutorial/data.rst
+++ b/doc/build/tutorial/data.rst
@@ -5,6 +5,8 @@
 
 .. include:: tutorial_nav_include.rst
 
+.. rst-class:: core-header, orm-addin
+
 .. _tutorial_working_with_data:
 
 Working with Data

diff --git a/doc/build/tutorial/data_insert.rst b/doc/build/tutorial/data_insert.rst
index 0d745cb319ccec08d6443ecc4920ffda11d2c97b..765b6890b6e1df662e1c0849318fc4039dc14d6f 100644 (file)
--- a/doc/build/tutorial/data_insert.rst
+++ b/doc/build/tutorial/data_insert.rst
@@ -5,9 +5,7 @@
 
 .. include:: tutorial_nav_include.rst
 
-
-.. rst-class:: core-header
-
+.. rst-class:: core-header, orm-addin
 
 .. _tutorial_core_insert:
 

diff --git a/doc/build/tutorial/engine.rst b/doc/build/tutorial/engine.rst
index fc8973c465910e1f5b4829d8acc4f5fbbfc5b344..4e53ae6bf9c5821863b2caebf2cf4348d7d0b59e 100644 (file)
--- a/doc/build/tutorial/engine.rst
+++ b/doc/build/tutorial/engine.rst
@@ -3,11 +3,19 @@
 
 .. include:: tutorial_nav_include.rst
 
+.. rst-class:: core-header, orm-addin
+
 .. _tutorial_engine:
 
 Establishing Connectivity - the Engine
 ==========================================
 
+.. container:: orm-header
+
+    **Welcome ORM and Core readers alike!**
+
+    Every SQLAlchemy application that connects to a database needs to use
+    an :class:`_engine.Engine`.  This short section is for everyone.
 
 The start of any SQLAlchemy application is an object called the
 :class:`_future.Engine`.   This object acts as a central source of connections

diff --git a/doc/build/tutorial/index.rst b/doc/build/tutorial/index.rst
index cb6c2feae3afc3fc0de41dbbd390490800416023..2440a33ed08681e709347b874c77cad6a6fa8ad2 100644 (file)
--- a/doc/build/tutorial/index.rst
+++ b/doc/build/tutorial/index.rst
@@ -42,9 +42,14 @@ These APIs are known as **Core** and **ORM**.
     to a database, interacting with database queries and results, and
     programmatic construction of SQL statements.
 
-    Sections that have a **dark blue border on the right** will discuss
-    concepts that are **primarily Core-only**; when using the ORM, these
-    concepts are still in play but are less often explicit in user code.
+    Sections that are **primarily Core-only** will not refer to the ORM.
+    SQLAlchemy constructs used in these sections will be imported from the
+    ``sqlalchemy`` namespace. As an additional indicator of subject
+    classification, they will also include a **dark blue border on the right**.
+    When using the ORM, these concepts are still in play but are less often
+    explicit in user code. ORM users should read these sections, but not expect
+    to be using these APIs directly for ORM-centric code.
+
 
 .. container:: orm-header
 
@@ -56,14 +61,28 @@ These APIs are known as **Core** and **ORM**.
     SQL Expression Language to allow SQL queries to be composed and invoked
     in terms of user-defined objects.
 
-    Sections that have a **light blue border on the left** will discuss
-    concepts that are **primarily ORM-only**.  Core-only users
-    can skip these.
+    Sections that are **primarily ORM-only** should be **titled to
+    include the phrase "ORM"**, so that it's clear this is an ORM related topic.
+    SQLAlchemy constructs used in these sections will be imported from the
+    ``sqlalchemy.orm`` namespace. Finally, as an additional indicator of
+    subject classification, they will also include a **light blue border on the
+    left**. Core-only users can skip these.
 
 .. container:: core-header, orm-dependency
 
-    A section that has **both light and dark borders on both sides** will
-    discuss a **Core concept that is also used explicitly with the ORM**.
+    **Most** sections in this tutorial discuss **Core concepts that
+    are also used explicitly with the ORM**. SQLAlchemy 2.0 in particular
+    features a much greater level of integration of Core API use within the
+    ORM.
+
+    For each of these sections, there will be **introductory text** discussing the
+    degree to which ORM users should expect to be using these programming
+    patterns. SQLAlchemy constructs in these sections will be imported from the
+    ``sqlalchemy`` namespace with some potential use of ``sqlalchemy.orm``
+    constructs at the same time. As an additional indicator of subject
+    classification, these sections will also include **both a thinner light
+    border on the left, and a thicker dark border on the right**. Core and ORM
+    users should familiarize with concepts in these sections equally.
 
 
 Tutorial Overview

diff --git a/doc/build/tutorial/orm_related_objects.rst b/doc/build/tutorial/orm_related_objects.rst
index 02ff2c17221188e729978dfd048efff83995093b..61ce5a1bd693f63b9f566cdc1140bbc73a87993c 100644 (file)
--- a/doc/build/tutorial/orm_related_objects.rst
+++ b/doc/build/tutorial/orm_related_objects.rst
@@ -5,11 +5,12 @@
 
 .. include:: tutorial_nav_include.rst
 
+.. rst-class:: orm-header
 
 .. _tutorial_orm_related_objects:
 
-Working with Related Objects
-============================
+Working with ORM Related Objects
+================================
 
 In this section, we will cover one more essential ORM concept, which is
 how the ORM interacts with mapped classes that refer to other objects. In the