- add some context to the declarative section indicating this is not

the introductory material for these topics

Change-Id: I358ba8c32520ce3950a727216bc019e33377e7b9

4 files changed, 25 insertions, 2 deletions

diff --git a/doc/build/orm/extensions/declarative/basic_use.rst b/doc/build/orm/extensions/declarative/basic_use.rst
index b23fa4044..63ab932c1 100644
--- a/doc/build/orm/extensions/declarative/basic_use.rst
+++ b/doc/build/orm/extensions/declarative/basic_use.rst
@@ -2,6 +2,13 @@
 Basic Use
 =========
 
+.. seealso::
+
+    This section describes specifics about how the Declarative system
+    interacts with the SQLAlchemy ORM.  For a general introduction
+    to class mapping, see :ref:`ormtutorial_toplevel` as well as
+    :ref:`mapper_config_toplevel`.
+
 SQLAlchemy object-relational configuration involves the
 combination of :class:`.Table`, :func:`.mapper`, and class
 objects to define a mapped class.
diff --git a/doc/build/orm/extensions/declarative/inheritance.rst b/doc/build/orm/extensions/declarative/inheritance.rst
index 20a51efb2..25ce986b7 100644
--- a/doc/build/orm/extensions/declarative/inheritance.rst
+++ b/doc/build/orm/extensions/declarative/inheritance.rst
@@ -10,8 +10,10 @@ as declarative will determine this from the class itself.   The various
 
 .. seealso::
 
-    :ref:`inheritance_toplevel` - general introduction to inheritance
-    mapping with Declarative.
+    This section describes some specific details on how the Declarative system
+    interacts with SQLAlchemy ORM inheritance configuration.  See
+    :ref:`inheritance_toplevel` for a general introduction to inheritance
+    mapping.
 
 Joined Table Inheritance
 ~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/build/orm/extensions/declarative/relationships.rst b/doc/build/orm/extensions/declarative/relationships.rst
index fb53c28bb..66eff40df 100644
--- a/doc/build/orm/extensions/declarative/relationships.rst
+++ b/doc/build/orm/extensions/declarative/relationships.rst
@@ -4,6 +4,13 @@
 Configuring Relationships
 =========================
 
+.. seealso::
+
+    This section describes specifics about how the Declarative system
+    interacts with SQLAlchemy ORM relationship constructs.  For general
+    information about setting up relationships between mappings,
+    see :ref:`ormtutorial_toplevel` and :ref:`relationship_patterns`.
+
 Relationships to other classes are done in the usual way, with the added
 feature that the class specified to :func:`~sqlalchemy.orm.relationship`
 may be a string name.  The "class registry" associated with ``Base``
diff --git a/doc/build/orm/extensions/declarative/table_config.rst b/doc/build/orm/extensions/declarative/table_config.rst
index f203c5580..a14deb6aa 100644
--- a/doc/build/orm/extensions/declarative/table_config.rst
+++ b/doc/build/orm/extensions/declarative/table_config.rst
@@ -4,6 +4,13 @@
 Table Configuration
 ===================
 
+.. seealso::
+
+    This section describes specifics about how the Declarative system
+    defines :class:`.Table` objects that are to be mapped with the
+    SQLAlchemy ORM.  For general information on :class:`.Table` objects
+    see :ref:`metadata_describing_toplevel`.
+
 Table arguments other than the name, metadata, and mapped Column
 arguments are specified using the ``__table_args__`` class attribute.
 This attribute accommodates both positional as well as keyword