- cross link for concrete helper classes

- remove redundant concrete helper docs from declarative docs,
two places is enough

3 files changed, 36 insertions, 71 deletions

diff --git a/doc/build/orm/extensions/declarative/inheritance.rst b/doc/build/orm/extensions/declarative/inheritance.rst
index bf0f2a6e1..20a51efb2 100644
--- a/doc/build/orm/extensions/declarative/inheritance.rst
+++ b/doc/build/orm/extensions/declarative/inheritance.rst
@@ -8,6 +8,11 @@ as possible.  The ``inherits`` mapper keyword argument is not needed
 as declarative will determine this from the class itself.   The various
 "polymorphic" keyword arguments are specified using ``__mapper_args__``.
 
+.. seealso::
+
+    :ref:`inheritance_toplevel` - general introduction to inheritance
+    mapping with Declarative.
+
 Joined Table Inheritance
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -41,10 +46,6 @@ only the ``engineers.id`` column, give it a different attribute name::
         primary_language = Column(String(50))
 
 
-.. versionchanged:: 0.7 joined table inheritance favors the subclass
-   column over that of the superclass, such as querying above
-   for ``Engineer.id``.  Prior to 0.7 this was the reverse.
-
 .. _declarative_single_table:
 
 Single Table Inheritance
@@ -247,72 +248,13 @@ before the class is built::
         __table__ = managers
         __mapper_args__ = {'polymorphic_identity':'manager', 'concrete':True}
 
-.. _declarative_concrete_helpers:
-
-Using the Concrete Helpers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Helper classes provides a simpler pattern for concrete inheritance.
-With these objects, the ``__declare_first__`` helper is used to configure the
-"polymorphic" loader for the mapper after all subclasses have been declared.
-
-An abstract base can be declared using the
-:class:`.AbstractConcreteBase` class::
-
-    from sqlalchemy.ext.declarative import AbstractConcreteBase
-
-    class Employee(AbstractConcreteBase, Base):
-        pass
-
-To have a concrete ``employee`` table, use :class:`.ConcreteBase` instead::
-
-    from sqlalchemy.ext.declarative import ConcreteBase
-
-    class Employee(ConcreteBase, Base):
-        __tablename__ = 'employee'
-        employee_id = Column(Integer, primary_key=True)
-        name = Column(String(50))
-        __mapper_args__ = {
-                        'polymorphic_identity':'employee',
-                        'concrete':True}
-
-
-Either ``Employee`` base can be used in the normal fashion::
-
-    class Manager(Employee):
-        __tablename__ = 'manager'
-        employee_id = Column(Integer, primary_key=True)
-        name = Column(String(50))
-        manager_data = Column(String(40))
-        __mapper_args__ = {
-                        'polymorphic_identity':'manager',
-                        'concrete':True}
-
-    class Engineer(Employee):
-        __tablename__ = 'engineer'
-        employee_id = Column(Integer, primary_key=True)
-        name = Column(String(50))
-        engineer_info = Column(String(40))
-        __mapper_args__ = {'polymorphic_identity':'engineer',
-                        'concrete':True}
-
-
-The :class:`.AbstractConcreteBase` class is itself mapped, and can be
-used as a target of relationships::
-
-    class Company(Base):
-        __tablename__ = 'company'
-
-        id = Column(Integer, primary_key=True)
-        employees = relationship("Employee",
-                        primaryjoin="Company.id == Employee.company_id")
-
-
-.. versionchanged:: 0.9.3 Support for use of :class:`.AbstractConcreteBase`
-   as the target of a :func:`.relationship` has been improved.
+The helper classes :class:`.AbstractConcreteBase` and :class:`.ConcreteBase`
+provide automation for the above system of creating a polymorphic union.
+See the documentation for these helpers as well as the main ORM documentation
+on concrete inheritance for details.
 
-It can also be queried directly::
+.. seealso::
 
-    for employee in session.query(Employee).filter(Employee.name == 'qbert'):
-        print(employee)
+    :ref:`concrete_inheritance`
 
+    :ref:`inheritance_concrete_helpers`
diff --git a/doc/build/orm/inheritance.rst b/doc/build/orm/inheritance.rst
index 6434d7a05..f640973c4 100644
--- a/doc/build/orm/inheritance.rst
+++ b/doc/build/orm/inheritance.rst
@@ -670,6 +670,9 @@ Two critical points should be noted:
   mapped in an inheritance relationship with ``Employee``, they still **do not
   include polymorphic loading**.
 
+Concrete Polymorphic Loading
++++++++++++++++++++++++++++++
+
 To load polymorphically, the :paramref:`.orm.mapper.with_polymorphic` argument is required, along
 with a selectable indicating how rows should be loaded.   Polymorphic loading
 is most inefficient with concrete inheritance, so if we do seek this style of
@@ -767,6 +770,11 @@ them to each class using ``__table__``::
         __table__ = manager_table
         __mapper_args__ = {'polymorphic_identity':'manager', 'concrete':True}
 
+.. _inheritance_concrete_helpers:
+
+Using the Declarative Helper Classes
++++++++++++++++++++++++++++++++++++++
+
 Another way is to use a special helper class that takes on the fairly
 complicated task of deferring the production of :class:`.Mapper` objects
 until all table metadata has been collected, and the polymorphic union to which
@@ -870,7 +878,6 @@ can produce this; the mapping would be::
 
     :ref:`declarative_concrete_table` - in the Declarative reference documentation
 
-    :ref:`declarative_concrete_helpers` - in the Declarative reference documentation
 
 Using Relationships with Inheritance
 ------------------------------------
diff --git a/lib/sqlalchemy/ext/declarative/api.py b/lib/sqlalchemy/ext/declarative/api.py
index dfc47ce95..5fe427bc2 100644
--- a/lib/sqlalchemy/ext/declarative/api.py
+++ b/lib/sqlalchemy/ext/declarative/api.py
@@ -397,6 +397,15 @@ class ConcreteBase(object):
                             'polymorphic_identity':'manager',
                             'concrete':True}
 
+    .. seealso::
+
+        :class:`.AbstractConcreteBase`
+
+        :ref:`concrete_inheritance`
+
+        :ref:`inheritance_concrete_helpers`
+
+
     """
 
     @classmethod
@@ -495,6 +504,13 @@ class AbstractConcreteBase(ConcreteBase):
        have been reworked to support relationships established directly
        on the abstract base, without any special configurational steps.
 
+    .. seealso::
+
+        :class:`.ConcreteBase`
+
+        :ref:`concrete_inheritance`
+
+        :ref:`inheritance_concrete_helpers`
 
     """