From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 3 Mar 2022 15:33:14 +0000 (-0500)
Subject: quick doc adjustments
X-Git-Tag: rel_2_0_0b1~456
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f68a51c549754637bd59213101025f1ee63e4865;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

quick doc adjustments

tweet thread:  https://twitter.com/zzzeek/status/1499397255089909762

Change-Id: I5556ef707c2285e7b64c91ae5c58af52efcf4770
---

diff --git a/doc/build/index.rst b/doc/build/index.rst
index 26fa1ff8a4..3be6b4726a 100644
--- a/doc/build/index.rst
+++ b/doc/build/index.rst
@@ -16,16 +16,11 @@ SQLAlchemy Documentation
 
   .. container::
 
-    A high level view and getting set up.
+    New to SQLAlchemy?   Start here:
 
-    :doc:`Overview <intro>` |
-    :ref:`Installation Guide <installation>` |
-    :doc:`Frequently Asked Questions <faq/index>` |
-    :doc:`Migration from 1.4 <changelog/migration_20>` |
-    :doc:`Glossary <glossary>` |
-    :doc:`Error Messages <errors>` |
-    :doc:`Changelog catalog <changelog/index>`
+    * **For Python Beginners:** :ref:`Installation Guide <installation>` - basic guidance on installing with pip and similar
 
+    * **For Python Veterans:** :doc:`SQLAlchemy Overview <intro>` - brief architectural overview
 
 .. container:: left_right_container
 
@@ -35,25 +30,29 @@ SQLAlchemy Documentation
 
         Tutorials
 
-  ..  the paragraph below for "sqlalchemy 2.0" seems to be too wide to be
-      easily readable.  suggest some kind of layout change that can keep the
-      paragraph width more narrow even if there is just one row on the page.
-
   .. container::
 
-    **SQLAlchemy 2.0**
-
     The SQLAlchemy 2.0 series represents a major rework of the classic 1.x
-    SQLAlchemy APIs that have evolved over more than 15 years.   The
-    SQLAlchemy tutorial provides a holistic view of the library, integrating
-    Core and ORM features in a narrative style that is optimized towards
-    establishing a solid understanding of the foundations upon which
-    SQLAlchemy is built on.  The tutorials are recommended for all new users
-    as well as veterans of older SQLAlchemy versions alike.
+    SQLAlchemy APIs that have evolved over more than 15 years. The new tutorial
+    is recommended for all new users as well as veterans of older SQLAlchemy
+    versions alike.
+
+    * **For all users:** :doc:`/tutorial/index` - SQLAlchemy 2.0's main tutorial
+
+
+.. container:: left_right_container
+
+  .. container:: leftmost
+
+      .. rst-class:: h2
+
+        Migration Notes
 
-    * :doc:`/tutorial/index` - SQLAlchemy 2.0's main tutorial
+  .. container::
 
     * :doc:`Migrating to SQLAlchemy 2.0 <changelog/migration_20>` - Complete background on migrating from 1.3 or 1.4 to 2.0
+    * :doc:`Changelog catalog <changelog/index>` - Detailed changelogs for all SQLAlchemy Versions
+
 
 .. container:: left_right_container
 
@@ -145,3 +144,18 @@ SQLAlchemy Documentation
 
       :doc:`More Dialects ... <dialects/index>`
 
+.. container:: left_right_container
+
+  .. container:: leftmost
+
+      .. rst-class:: h2
+
+        Supplementary
+
+  .. container::
+
+    * :doc:`Frequently Asked Questions <faq/index>` - A collection of common problems and solutions
+    * :doc:`Glossary <glossary>` - Terms used in SQLAlchemy's documentation
+    * :doc:`Error Message Guide <errors>` - Explainations of many SQLAlchemy Errors
+    * :doc:`Complete table of of contents <contents>`
+    * :doc:`Index <index>`
diff --git a/doc/build/intro.rst b/doc/build/intro.rst
index fba3c160a1..dcc672a9d4 100644
--- a/doc/build/intro.rst
+++ b/doc/build/intro.rst
@@ -243,6 +243,12 @@ Python prompt like this:
      >>> sqlalchemy.__version__ # doctest: +SKIP
      2.0.0
 
+Next Steps
+----------
+
+With SQLAlchemy installed, new and old users alike can
+:ref:`Proceed to the SQLAlchemy Tutorial <unified_tutorial>`.
+
 .. _migration:
 
 1.x to 2.0 Migration