- mega example cleanup

- added READMEs to all examples in each __init__.py and added to sphinx documentation
- added versioning example
- removed vertical/vertical.py, the dictlikes are more straightforward

2 files changed, 34 insertions, 36 deletions

diff --git a/examples/postgis/__init__.py b/examples/postgis/__init__.py
index e69de29bb..1a351f7ae 100644
--- a/examples/postgis/__init__.py
+++ b/examples/postgis/__init__.py
@@ -0,0 +1,34 @@
+"""A naive example illustrating techniques to help 
+embed PostGIS functionality.
+
+This example was originally developed in the hopes that it would be extrapolated into a comprehensive PostGIS integration layer.  We are pleased to announce that this has come to fruition as `GeoAlchemy <http://www.geoalchemy.org/>`_.
+
+The example illustrates:
+
+* a DDL extension which allows CREATE/DROP to work in 
+  conjunction with AddGeometryColumn/DropGeometryColumn
+  
+* a Geometry type, as well as a few subtypes, which
+  convert result row values to a GIS-aware object,
+  and also integrates with the DDL extension.
+
+* a GIS-aware object which stores a raw geometry value
+  and provides a factory for functions such as AsText().
+  
+* an ORM comparator which can override standard column
+  methods on mapped objects to produce GIS operators.
+  
+* an attribute event listener that intercepts strings
+  and converts to GeomFromText().
+  
+* a standalone operator example.
+
+The implementation is limited to only public, well known
+and simple to use extension points. 
+
+E.g.::
+
+    print session.query(Road).filter(Road.road_geom.intersects(r1.road_geom)).all()
+
+"""
+
diff --git a/examples/postgis/postgis.py b/examples/postgis/postgis.py
index d84648a95..d3f728293 100644
--- a/examples/postgis/postgis.py
+++ b/examples/postgis/postgis.py
@@ -1,39 +1,3 @@
-"""A naive example illustrating techniques to help 
-embed PostGIS functionality.
-
-The techniques here could be used by a capable developer 
-as the basis for a comprehensive PostGIS SQLAlchemy extension.
-Please note this is an entirely incomplete proof of concept
-only, and PostGIS support is *not* a supported feature 
-of SQLAlchemy.
-
-Includes:
-
- * a DDL extension which allows CREATE/DROP to work in 
-   conjunction with AddGeometryColumn/DropGeometryColumn
-   
- * a Geometry type, as well as a few subtypes, which
-   convert result row values to a GIS-aware object,
-   and also integrates with the DDL extension.
-
- * a GIS-aware object which stores a raw geometry value
-   and provides a factory for functions such as AsText().
-   
- * an ORM comparator which can override standard column
-   methods on mapped objects to produce GIS operators.
-   
- * an attribute event listener that intercepts strings
-   and converts to GeomFromText().
-   
- * a standalone operator example.
-
-The implementation is limited to only public, well known
-and simple to use extension points. Future SQLAlchemy
-expansion points may allow more seamless integration of
-some features.
-
-"""
-
 from sqlalchemy.orm.interfaces import AttributeExtension
 from sqlalchemy.orm.properties import ColumnProperty
 from sqlalchemy.types import TypeEngine