- 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.

3 files changed, 18 insertions, 25 deletions

diff --git a/examples/elementtree/__init__.py b/examples/elementtree/__init__.py
index 6462dd562..66e9cfbbe 100644
--- a/examples/elementtree/__init__.py
+++ b/examples/elementtree/__init__.py
@@ -7,26 +7,6 @@ native cElementTree as well as lxml, and can be adapted to
 suit any kind of DOM representation system. Querying along
 xpath-like strings is illustrated as well.
 
-In order of complexity:
-
-* ``pickle.py`` - Quick and dirty, serialize the whole DOM into a BLOB
-  column.  While the example   is very brief, it has very limited
-  functionality.
-
-* ``adjacency_list.py`` - Each DOM node is stored in an individual
-  table row, with attributes   represented in a separate table.  The
-  nodes are associated in a hierarchy using an adjacency list
-  structure.  A query function is introduced which can search for nodes
-  along any path with a given   structure of attributes, basically a
-  (very narrow) subset of xpath.
-
-* ``optimized_al.py`` - Uses the same strategy as
-  ``adjacency_list.py``, but associates each   DOM row with its owning
-  document row, so that a full document of DOM nodes can be   loaded
-  using O(1) queries - the construction of the "hierarchy" is performed
-  after the load in a non-recursive fashion and is much more
-  efficient.
-
 E.g.::
 
     # parse an XML file and persist in the database
@@ -39,4 +19,7 @@ E.g.::
         # dump the XML
         print document
 
+.. autosource::
+    :files: pickle.py, adjacency_list.py, optimized_al.py
+
 """
\ No newline at end of file
diff --git a/examples/elementtree/adjacency_list.py b/examples/elementtree/adjacency_list.py
index a3ad42778..5e27ba9ca 100644
--- a/examples/elementtree/adjacency_list.py
+++ b/examples/elementtree/adjacency_list.py
@@ -1,9 +1,17 @@
-"""illustrates an explicit way to persist an XML document expressed using ElementTree.
+"""Illustrates an explicit way to persist an XML document expressed using ElementTree.
+
+Each DOM node is stored in an individual
+table row, with attributes   represented in a separate table.  The
+nodes are associated in a hierarchy using an adjacency list
+structure.  A query function is introduced which can search for nodes
+along any path with a given   structure of attributes, basically a
+(very narrow) subset of xpath.
 
 This example explicitly marshals/unmarshals the ElementTree document into
 mapped entities which have their own tables.  Compare to pickle.py which
 uses pickle to accomplish the same task.  Note that the usage of both
 styles of persistence are identical, as is the structure of the main Document class.
+
 """
 
 ################################# PART I - Imports/Coniguration ####################################
diff --git a/examples/elementtree/optimized_al.py b/examples/elementtree/optimized_al.py
index 1dbad0943..e13f5b0ee 100644
--- a/examples/elementtree/optimized_al.py
+++ b/examples/elementtree/optimized_al.py
@@ -1,7 +1,9 @@
-"""This script duplicates adjacency_list.py, but optimizes the loading
-of XML nodes to be based on a "flattened" datamodel. Any number of XML documents,
-each of arbitrary complexity, can be loaded in their entirety via a single query
-which joins on only three tables.
+"""Uses the same strategy as
+  ``adjacency_list.py``, but associates each   DOM row with its owning
+  document row, so that a full document of DOM nodes can be loaded
+  using O(1) queries - the construction of the "hierarchy" is performed
+  after the load in a non-recursive fashion and is more
+  efficient.
 
 """