From 8d5986fafd8360ddfe3992bd56602d5a52a23392 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Wed, 8 Mar 2023 10:10:14 -0500 Subject: [PATCH] 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 --- doc/build/tutorial/data.rst | 2 ++ doc/build/tutorial/data_insert.rst | 4 +-- doc/build/tutorial/engine.rst | 8 +++++ doc/build/tutorial/index.rst | 35 +++++++++++++++++----- doc/build/tutorial/orm_related_objects.rst | 5 ++-- 5 files changed, 41 insertions(+), 13 deletions(-) diff --git a/doc/build/tutorial/data.rst b/doc/build/tutorial/data.rst index 1d5dde7b84..3242710a92 100644 --- 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 2415f21f35..07e5f90328 100644 --- 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 80c20e566e..586edda0e1 100644 --- 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:`_engine.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 213162d3f8..ef4bb76345 100644 --- 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 902881c782..69224ba78b 100644 --- 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 -- 2.47.3