- start reworking examples to include more code from the wiki.

- add the other versioning examples from the wiki
- modernize the dictlike examples

1 files changed, 68 insertions, 47 deletions

diff --git a/doc/build/orm/examples.rst b/doc/build/orm/examples.rst
index 60d075a36..484865e7e 100644
--- a/doc/build/orm/examples.rst
+++ b/doc/build/orm/examples.rst
@@ -1,18 +1,21 @@
 .. _examples_toplevel:
 
-Examples
-========
+============
+ORM Examples
+============
 
 The SQLAlchemy distribution includes a variety of code examples illustrating
 a select set of patterns, some typical and some not so typical.   All are
 runnable and can be found in the ``/examples`` directory of the
-distribution.   Each example contains a README in its ``__init__.py`` file,
-each of which are listed below.
+distribution.   Descriptions and source code for all can be found here.
 
 Additional SQLAlchemy examples, some user contributed, are available on the
 wiki at `<http://www.sqlalchemy.org/trac/wiki/UsageRecipes>`_.
 
 
+Mapping Recipes
+===============
+
 .. _examples_adjacencylist:
 
 Adjacency List
@@ -27,80 +30,98 @@ Associations
 
 .. automodule:: examples.association
 
-
-.. _examples_instrumentation:
-
-Attribute Instrumentation
--------------------------
-
-.. automodule:: examples.custom_attributes
-
-.. _examples_caching:
-
-Dogpile Caching
----------------
-
-.. automodule:: examples.dogpile_caching
-
 Directed Graphs
 ---------------
 
 .. automodule:: examples.graphs
 
 Dynamic Relations as Dictionaries
-----------------------------------
+------------------------------------
 
 .. automodule:: examples.dynamic_dict
 
 .. _examples_generic_associations:
 
 Generic Associations
---------------------
+------------------------
 
 .. automodule:: examples.generic_associations
 
-.. _examples_sharding:
-
-Horizontal Sharding
--------------------
-
-.. automodule:: examples.sharding
-
-Inheritance Mappings
---------------------
-
-.. automodule:: examples.inheritance
-
 Large Collections
------------------
+------------------------
 
 .. automodule:: examples.large_collection
 
 Nested Sets
------------
+------------
 
 .. automodule:: examples.nested_sets
 
-.. _examples_postgis:
+.. _examples_xmlpersistence:
 
-PostGIS Integration
--------------------
+XML Persistence
+------------------------
 
-.. automodule:: examples.postgis
+.. automodule:: examples.elementtree
+
+Versioning Objects
+------------------------
+
+Versioning with a History Table
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: examples.versioned_history
 
-Versioned Objects
------------------
+Versioning using Temporal Rows
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. automodule:: examples.versioning
+.. automodule:: examples.versioned_rows
 
 Vertical Attribute Mapping
---------------------------
+------------------------------------
 
 .. automodule:: examples.vertical
 
-.. _examples_xmlpersistence:
 
-XML Persistence
----------------
+Inheritance Mapping Recipes
+============================
+
+Basic Inheritance Mappings
+----------------------------------
+
+.. automodule:: examples.inheritance
+
+Special APIs
+============
+
+.. _examples_instrumentation:
+
+Attribute Instrumentation
+------------------------------------
+
+.. automodule:: examples.custom_attributes
+
+.. _examples_sharding:
+
+Horizontal Sharding
+------------------------
+
+.. automodule:: examples.sharding
+
+Extending the ORM
+=================
+
+.. _examples_caching:
+
+Dogpile Caching
+------------------------
+
+.. automodule:: examples.dogpile_caching
+
+.. _examples_postgis:
+
+PostGIS Integration
+------------------------
+
+.. automodule:: examples.postgis
 
-.. automodule:: examples.elementtree