[mousetrap/gnome3-wip: 205/240] Document built-in config file and add `--dump-annotated`.

[Heidi Ellis <heidiellis src gnome org>]

commit 6e035e048b79eb8e3da1c00fd1ed8c9e8c5a0dda
Author: Stoney Jackson <dr stoney gmail com>
Date:   Sun Jun 29 10:00:26 2014 -0400

    Document built-in config file and add `--dump-annotated`.
    
    We want to keep the documentation of the configuration file
    as close to the source as possible. What better way than to
    put the documentation in the configuration file itself?
    
    To give the user convenient access to this annotated
    configuration file. I add `--dump-annotated` command-line
    option. This is needed since `--dump-config` dumps the
    parsed and merged configurations on the search path, which
    does not preserve comments.

 README.md                    |   24 ++++++++++++++++--------
 src/mousetrap/config.py      |    4 ++++
 src/mousetrap/main.py        |   29 +++++++++++++++++++----------
 src/mousetrap/mousetrap.yaml |   28 ++++++++++++++++++++++++++++
 4 files changed, 67 insertions(+), 18 deletions(-)
---
diff --git a/README.md b/README.md
index 44bbd7b..d0ee598 100644
--- a/README.md
+++ b/README.md
@@ -50,19 +50,27 @@ close your left eye for about 1.5 seconds.
 
 ## Configuring
 
-MouseTrap loads its configuration from following in order:
+To customize MouseTrap's configuration, place a copy of the annotated built-in
+configuration in ~/.mousetrap.xml, and then edit it.
 
-* The built-in default configuration
-* ~/.mousetrap.yaml
-* $PWD/.mousetrap.yaml
-* $PWD/mousetrap.yaml
-* From the file specified using the `--config` option.
-For example: `mousetrap --config path/to/myconfig.yaml`
+    mousetrap --dump-annotated > ~/.mousetrap.yaml
 
-You can dump the current configuration as follows
+MouseTrap loads its configuration from the following locations in order. Later
+locations may override values of those that come before it.
+
+* Built-in: something like `/usr/local/lib/python2.7/mousetrap/mousetrap.yaml`
+* User: `~/.mousetrap.yaml`
+* Local hidden: `$PWD/.mousetrap.yaml`
+* Local: `$PWD/mousetrap.yaml`
+* Command-line: `mousetrap --config path/to/myconfig.yaml`
+
+Load and dump configuration:
 
     mousetrap --dump-config
 
+Dump built-in annotated configuration.
+
+    mouestrap --dump-annotated
 
 ## Translating
 
diff --git a/src/mousetrap/config.py b/src/mousetrap/config.py
index f9ba5e3..ae39a56 100644
--- a/src/mousetrap/config.py
+++ b/src/mousetrap/config.py
@@ -15,6 +15,10 @@ class Config(dict):
         ('user_specified_file', None),
         ])
 
+    @classmethod
+    def get_config_path(cls, key):
+        return cls.SEARCH_PATH[key]
+
     def __init__(self, user_specified_file=None):
         self.SEARCH_PATH['user_specified_file']=user_specified_file
         self._load()
diff --git a/src/mousetrap/main.py b/src/mousetrap/main.py
index d233234..37d26a9 100644
--- a/src/mousetrap/main.py
+++ b/src/mousetrap/main.py
@@ -1,33 +1,42 @@
 '''
 Where it all begins.
 '''
+import argparse
+import logging
+import logging.config
+import sys
+import yaml
+
+from mousetrap.config import Config
 
 
-import argparse
 parser = argparse.ArgumentParser()
-parser.add_argument("--dump-config",
-        help="Loads and dumps configuration to standard out.",
-        action="store_true")
 parser.add_argument("--config",
         metavar="FILE",
         help="Loads configuration from FILE.")
+parser.add_argument("--dump-config",
+        help="Loads and dumps current configuration to standard out.",
+        action="store_true")
+parser.add_argument("--dump-annotated",
+        help="Dumps default configuration (with comments) to standard out.",
+        action="store_true")
 args = parser.parse_args()
 
 
-from mousetrap.config import Config
+if args.dump_annotated:
+    with open(Config.get_config_path('default'), 'r') as annotated_file:
+        print annotated_file.read()
+    sys.exit(0)
+
+
 CONFIG = Config(args.config)
 if args.dump_config:
-    import sys
-    import yaml
     print yaml.dump(dict(CONFIG), default_flow_style=False)
     sys.exit(0)
 
 
-import logging
-import logging.config
 logging.config.dictConfig(CONFIG['logging'])
 LOGGER = logging.getLogger('mousetrap.main')
-import yaml
 LOGGER.debug(yaml.dump(dict(CONFIG), default_flow_style=False))
 
 
diff --git a/src/mousetrap/mousetrap.yaml b/src/mousetrap/mousetrap.yaml
index a0272d4..d9dcf0a 100644
--- a/src/mousetrap/mousetrap.yaml
+++ b/src/mousetrap/mousetrap.yaml
@@ -1,12 +1,28 @@
+# assembly - A list of puglin classes to load and run. Order matters.
+#            To enable a plugin, list it here.
 assembly:
 - mousetrap.plugins.camera.CameraPlugin
 - mousetrap.plugins.display.DisplayPlugin
 - mousetrap.plugins.nose.NoseJoystickPlugin
 - mousetrap.plugins.eyes.EyesPlugin
+
+
+# camera - Configuration for the built-in camera.
 camera:
+
+  # If you have more than one camera and you know the index of the one you
+  # want, set it here. Otherwise -1 will search for the first camera device.
   device_index: -1
+
+  # Dimensions of image produced by camera. These are hints. Actual image
+  # dimensions may be smaller and are device dependent.
   height: 300
   width: 400
+
+
+# classes - A mapping of class configurations indexed by class name.
+#           If you are installing a plugin, it may want you to add an
+#           entry here to configure it.
 classes:
   mousetrap.plugins.display.DisplayPlugin:
     window_title: MouseTrap
@@ -34,11 +50,19 @@ classes:
       scale_factor: 1.1
   mousetrap.plugins.nose.NoseJoystickPlugin:
     threshold: 5
+
+# haar_files - A mapping of haar cascade files. Relative paths are relative
+#              to the mousetrap package directory. Plugins, if they come with
+#              custome haar cascades, may ask you to add entries.
 haar_files:
   face: haars/haarcascade_frontalface_default.xml
   left_eye: haars/haarcascade_mcs_lefteye.xml
   nose: haars/haarcascade_mcs_nose.xml
   open_eye: haars/haarcascade_eye.xml
+
+# logging - Configuration controlling the logging mechanism used during normal
+# operation.  Its structure is defined by Python's built-in logging package.
+# For documentation, see https://docs.python.org/2/library/logging.html .
 logging:
   formatters:
     default:
@@ -56,6 +80,10 @@ logging:
     - console
     level: DEBUG
   version: 1
+
+# logging - Configuration controlling the logging mechanism used during
+# testing.  Its structure is defined by Python's built-in logging package.  For
+# documentation, see https://docs.python.org/2/library/logging.html .
 logging-test:
   formatters:
     default: