Example documentation and alignment of the code with the documentation

docs/source/example.rst

@@ -0,0 +1,57 @@
+Example
+=======
+
+Initializing the example
+------------------------
+
+Along side the ``pkgmeta`` package will is an example directory which contains
+an example configuration and a small script to populate the repository with
+faux distributions.
+
+To initialize the example, change directories to the project root::
+
+    $ cd [where ever pkgmeta is located]
+    $ ls
+    README.rst  docs        example     pkgmeta
+
+Run the ``make.py`` script::
+
+    $ PYTHONPATH=. python3.2 example/make.py
+    Creating the repository directory: ~/example-repo
+    Populating repository with example data...
+    Using configuration: ./example/example.cfg
+    Reading configuration...
+    Loaded 9 distributions into the repository
+
+Walk through
+------------
+
+Now that we've created an example repository, we can probe it for information.
+
+A brief example might be to search for distributions containing the term
+``cal``::
+
+    $ PYTHONPATH=. python3.2 pkgmeta/cli.py -c example/example.cfg search cal
+    p   solarcal          - Calendar based on solar dates.                          
+    p   webcal            - Web calendaring application
+
+Notice that we passed in the example configuration with the ``-c`` option.
+
+Now that we've found some distributions, let's try showing the distributions
+metadata::
+
+    $ PYTHONPATH=. python3.2 pkgmeta/cli.py -c example/example.cfg show webcal
+    Metadata-Version: 1.2
+    Name: webcal
+    Version: 3.0
+    Summary: Web calendaring application
+    Description: UNKNOWN
+    Home-page: UNKNOWN
+    Author: Hathor
+    Author-email: UNKNOWN
+    Maintainer: UNKNOWN
+    Maintainer-email: UNKNOWN
+    License: UNKNOWN
+    Download-URL: UNKNOWN
+    Requires-Dist: solarcal, sandbox (>=4.0), waterweb (>=8.0), soapbar (>=6.1)
+    Requires-Python: UNKNOWN

docs/source/index.rst

@@ -38,6 +38,7 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   example
    config
    tests
 

example/example.cfg

@@ -3,4 +3,4 @@ default = main
 
 [main]
 type = filesystem
-location = ~/example-main
+location = ~/example-repo

example/make.py

@@ -10,9 +10,9 @@
 
 def main():
     # Must create the repository location before we read in the configuration.
-    repository_location = os.path.expanduser('~/example-main')
+    repository_location = os.path.expanduser('~/example-repo')
     if not os.path.exists(repository_location):
-        print("Creating the main repository directory.")
+        print("Creating the repository directory: %s" % repository_location)
         os.mkdir(repository_location)
 
         print("Populating repository with example data...")
@@ -21,7 +21,7 @@ def main():
     cfg_file = os.path.join(HERE, 'example.cfg')
     print("Using configuration: %s" % cfg_file)
 
-    print("Read configuration...")
+    print("Reading configuration...")
     config = PkgMetaConfig.from_file(cfg_file)
     repo_config = config.get_repository_config()