- 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, 20 insertions, 18 deletions

diff --git a/examples/sharding/__init__.py b/examples/sharding/__init__.py
index e69de29bb..19f6db245 100644
--- a/examples/sharding/__init__.py
+++ b/examples/sharding/__init__.py
@@ -0,0 +1,20 @@
+"""a basic example of using the SQLAlchemy Sharding API.
+Sharding refers to horizontally scaling data across multiple
+databases.
+
+The basic components of a "sharded" mapping are:
+
+* multiple databases, each assigned a 'shard id'
+* a function which can return a single shard id, given an instance
+  to be saved; this is called "shard_chooser"
+* a function which can return a list of shard ids which apply to a particular
+  instance identifier; this is called "id_chooser".  If it returns all shard ids,
+  all shards will be searched.
+* a function which can return a list of shard ids to try, given a particular 
+  Query ("query_chooser").  If it returns all shard ids, all shards will be 
+  queried and the results joined together.
+
+In this example, four sqlite databases will store information about
+weather data on a database-per-continent basis.  We provide example shard_chooser, id_chooser and query_chooser functions.  The query_chooser illustrates inspection of the SQL expression element in order to attempt to determine a single shard being requested.
+
+"""
diff --git a/examples/sharding/attribute_shard.py b/examples/sharding/attribute_shard.py
index 2ac0c88ff..89d4243fc 100644
--- a/examples/sharding/attribute_shard.py
+++ b/examples/sharding/attribute_shard.py
@@ -1,21 +1,3 @@
-"""a basic example of using the SQLAlchemy Sharding API.
-Sharding refers to horizontally scaling data across multiple
-databases.
-
-In this example, four sqlite databases will store information about
-weather data on a database-per-continent basis.
-
-To set up a sharding system, you need:
-    1. multiple databases, each assined a 'shard id'
-    2. a function which can return a single shard id, given an instance
-    to be saved; this is called "shard_chooser"
-    3. a function which can return a list of shard ids which apply to a particular
-    instance identifier; this is called "id_chooser".  If it returns all shard ids,
-    all shards will be searched.
-    4. a function which can return a list of shard ids to try, given a particular 
-    Query ("query_chooser").  If it returns all shard ids, all shards will be 
-    queried and the results joined together.
-"""
 
 # step 1. imports
 from sqlalchemy import (create_engine, MetaData, Table, Column, Integer,