clarify alternative mapping example

this second example is not part of the doctest steps,
clarify that it's not part of code examples to be present
in execution steps.   Add an extra registry +
declarative base on top
so that even if someone does run it, the Base will have
been reset and the examples will continue to work
(noting that column order in statements may change, but
probably nothing else).

Fixes: #7891
Change-Id: Icb1ba310230841e502185d9d0cadd3c18d467292

diff --git a/doc/build/tutorial/metadata.rst b/doc/build/tutorial/metadata.rst
index afaf9d6100e7b9fca86c185abf995bb6d96ebdd3..6444ed692e074bf5f2c5b8374310ffce31764ba7 100644 (file)
--- a/doc/build/tutorial/metadata.rst
+++ b/doc/build/tutorial/metadata.rst
@@ -443,6 +443,9 @@ This form is called  :ref:`hybrid table <orm_imperative_table_configuration>`,
 and it consists of assigning to the ``.__table__`` attribute directly, rather
 than having the declarative process generate it::
 
+    mapper_registry = registry()
+    Base = mapper_registry.generate_base()
+
     class User(Base):
         __table__ = user_table
 
@@ -459,6 +462,15 @@ than having the declarative process generate it::
         def __repr__(self):
             return f"Address({self.email_address!r})"
 
+.. note:: The above example is an **alternative form** to the mapping that's
+   first illustrated previously at :ref:`tutorial_declaring_mapped_classes`.
+   This example is for illustrative purposes only, and is not part of this
+   tutorial's "doctest" steps, and as such does not need to be run for readers
+   who are executing code examples. The mapping here and the one at
+   :ref:`tutorial_declaring_mapped_classes` produce equivalent mappings, but in
+   general one would use only **one** of these two forms for particular mapped
+   class.
+
 The above two classes are equivalent to those which we declared in the
 previous mapping example.