- add a new sphinx extension "viewsource". takes advantage of part of the viewcode extension

to allow ad-hoc display of the source of any file, as well as a "directory listing" structure.
- reorganize examples/ to take advantage of new extension.  in particular, keep moving all
the descriptive text for files etc. into module docstrings, taking more advantage of
self-documentation.

5 files changed, 19 insertions, 35 deletions

diff --git a/examples/dogpile_caching/__init__.py b/examples/dogpile_caching/__init__.py
index 00c386bda..2d986584b 100644
--- a/examples/dogpile_caching/__init__.py
+++ b/examples/dogpile_caching/__init__.py
@@ -50,35 +50,9 @@ The demo scripts themselves, in order of complexity, are run as follows::
 
    python examples/dogpile_caching/local_session_caching.py
 
-
-Listing of files:
-
-    environment.py - Establish the Session, a dictionary
-    of "regions", a sample cache region against a .dbm
-    file, data / cache file paths, and configurations,
-    bootstrap fixture data if necessary.
-
-    caching_query.py - Represent functions and classes
-    which allow the usage of Dogpile caching with SQLAlchemy.
-    Introduces a query option called FromCache.
-
-    model.py - The datamodel, which represents Person that has multiple
-    Address objects, each with PostalCode, City, Country
-
-    fixture_data.py - creates demo PostalCode, Address, Person objects
-    in the database.
-
-    helloworld.py - the basic idea.
-
-    relationship_caching.py - Illustrates how to add cache options on
-    relationship endpoints, so that lazyloads load from cache.
-
-    advanced.py - Further examples of how to use FromCache.  Combines
-    techniques from the first two scripts.
-
-    local_session_caching.py - Grok everything so far ?   This example
-    creates a new dogpile.cache backend that will persist data in a dictionary
-    which is local to the current session.   remove() the session
-    and the cache is gone.
+.. autosource::
+    :files: environment.py, caching_query.py, model.py, fixture_data.py, \
+          helloworld.py, relationship_caching.py, advanced.py, \
+          local_session_caching.py
 
 """
diff --git a/examples/dogpile_caching/caching_query.py b/examples/dogpile_caching/caching_query.py
index 7fe84bede..9ac0d431a 100644
--- a/examples/dogpile_caching/caching_query.py
+++ b/examples/dogpile_caching/caching_query.py
@@ -1,7 +1,8 @@
 """caching_query.py
 
-Represent persistence structures which allow the usage of
-dogpile.cache caching with SQLAlchemy.
+Represent functions and classes
+which allow the usage of Dogpile caching with SQLAlchemy.
+Introduces a query option called FromCache.
 
 The three new concepts introduced here are:
 
diff --git a/examples/dogpile_caching/local_session_caching.py b/examples/dogpile_caching/local_session_caching.py
index cf0083d2e..e6c712b4a 100644
--- a/examples/dogpile_caching/local_session_caching.py
+++ b/examples/dogpile_caching/local_session_caching.py
@@ -1,5 +1,10 @@
 """local_session_caching.py
 
+Grok everything so far ?   This example
+creates a new dogpile.cache backend that will persist data in a dictionary
+which is local to the current session.   remove() the session
+and the cache is gone.
+
 Create a new Dogpile cache backend that will store
 cached data local to the current Session.
 
diff --git a/examples/dogpile_caching/model.py b/examples/dogpile_caching/model.py
index 622d31e6a..75c0ad28a 100644
--- a/examples/dogpile_caching/model.py
+++ b/examples/dogpile_caching/model.py
@@ -1,6 +1,7 @@
-"""Model.   We are modeling Person objects with a collection
-of Address objects.  Each Address has a PostalCode, which
-in turn references a City and then a Country:
+"""model.py
+
+The datamodel, which represents Person that has multiple
+Address objects, each with PostalCode, City, Country.
 
 Person --(1..n)--> Address
 Address --(has a)--> PostalCode
diff --git a/examples/dogpile_caching/relation_caching.py b/examples/dogpile_caching/relationship_caching.py
index d40752e48..320ced48a 100644
--- a/examples/dogpile_caching/relation_caching.py
+++ b/examples/dogpile_caching/relationship_caching.py
@@ -1,5 +1,8 @@
 """relationship_caching.py
 
+Illustrates how to add cache options on
+relationship endpoints, so that lazyloads load from cache.
+
 Load a set of Person and Address objects, specifying that
 related PostalCode, City, Country objects should be pulled from long
 term cache.