Merge lp:~javier.collado/utah/bug1039555-autogenerate into lp:~utah/utah/bug1039555

[Javier Collado]

This branch makes it possible to autogenerate the man pages using the output from the parser objects in the scripts.

The trick is to generate a set of text files when the configuration file for sphinx is read. Those text files are later included in the manual pages directly.

[Max Brustkern (nuclearbob)]

In run_install_test, machinetype and installtype both use TYPE as the metavar. It's probably not a big deal, but maybe it would make more sense to use different ones? I like the rest of this.

[lp:~javier.collado/utah/bug1039555-autogenerate]

675. By Javier Collado on 2012-09-06

Updated TYPE to MACHINETYPE to avoid metavar duplication

Changed according to review comment from Max

[Javier Collado (javier.collado)]

I've changed TYPE to MACHINETYPE for the --machinetype option.

However, I've not updated TYPE to INSTALLTYPE because the long option itself is --type instead of --installtype. If you like I can update both. Please let me know what do you think.

[Max Brustkern (nuclearbob)]

TYPE for installtype sounds good to me, the main reason I didn't just call the variable type in the first place is that type means something in python. Woo automatic man pages!

review: Approve

=== modified file 'Makefile'
--- Makefile	2012-08-22 12:19:35 +0000
+++ Makefile	2012-09-06 07:23:19 +0000
@@ -28,5 +28,6 @@
 	rm -f utah/config
 	rm -f utah_*
 	rm -f utah-*
+	cd docs && make clean
 
 .PHONY: client clean manpages

=== modified file 'client-Makefile'
--- client-Makefile	2012-08-22 12:19:35 +0000
+++ client-Makefile	2012-09-06 07:23:19 +0000
@@ -11,5 +11,6 @@
 
 clean:
 	rm utah/config
+	cd docs && make clean
 
 .PHONY: clean manpages

=== modified file 'client.py'
--- client.py	2012-09-03 08:36:00 +0000
+++ client.py	2012-09-06 07:23:19 +0000
@@ -14,11 +14,10 @@
 from utah.client import exceptions
 
 
-def process_cmdline_argparse():
+def get_parser():
     """
     Process the command line arguments.
     """
-
     # requires Python2.7+
     import argparse
 
@@ -29,8 +28,10 @@
     parser.add_argument('-s', '--state-file',
                         help=('File to use for storing state (default "%s")'
                               % DEFAULT_STATE_FILE))
-    parser.add_argument('-f', '--format', choices=['text', 'yaml', 'json'],
-                        default='yaml', help='Output format (default "yaml")')
+    parser.add_argument('-f', '--format',
+                        choices=['text', 'yaml', 'json'],
+                        default='yaml',
+                        help='Output format (default "%(default)s")')
     parser.add_argument('-t', '--testdir',
                         default='/var/lib/utah', help='Main test directory')
     parser.add_argument('-r', '--runlist', type=url_argument,
@@ -45,13 +46,7 @@
     parser.add_argument('-d', '--debug', action='store_true',
                         help='Print debugging output')
 
-    args = parser.parse_args()
-
-    return args
-
-# TODO: write <2.7 optparse version and set based on version of python
-#       being used.
-process_cmdline = process_cmdline_argparse
+    return parser
 
 
 def exit(returncode, msg):
@@ -73,7 +68,10 @@
     """
     The main driver for the 'utah' application.
     """
-    args = process_cmdline()
+    # TODO: write <2.7 optparse version and set based on version of python
+    #       being used.
+    parser = get_parser()
+    args = parser.parse_args()
 
     # When resuming, this script is invoked as root by rc.local
     # No group membership is assigned then, so root needs to be able to run

=== modified file 'docs/Makefile'
--- docs/Makefile	2012-08-07 16:06:37 +0000
+++ docs/Makefile	2012-09-06 07:23:19 +0000
@@ -40,6 +40,7 @@
 
 clean:
 	-rm -rf $(BUILDDIR)/*
+	-rm source/man/*.txt  # Autogenerated content for man pages
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

=== modified file 'docs/source/conf.py'
--- docs/source/conf.py	2012-09-05 06:59:28 +0000
+++ docs/source/conf.py	2012-09-06 07:23:19 +0000
@@ -12,11 +12,14 @@
 # serve to show the default.
 
 import sys, os
+import itertools
+import re
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath('../../examples'))
 
 
 class Mock(type):
@@ -35,6 +38,78 @@
                  'apt', 'apt.cache'):
     sys.modules[mod_name] = Mock(mod_name, (type,), {})
 
+
+# Autogenerate help contents for manual pages when building manual pages
+# Note: This assumes that sphinx-build is called as in the makefile like this:
+# /usr/bin/sphinx-build -b man <sphinx_opts>
+if sys.argv[2] == 'man':
+    def get_parser_strings(script_name, parser):
+        description = parser.description
+
+        help_lines = parser.format_help().splitlines()
+        options_lines = itertools.dropwhile(
+                lambda l: l != 'optional arguments:',
+                help_lines)  # Drop usage
+        options_lines = itertools.takewhile(
+                lambda l: bool(l),
+                options_lines)  # Drop epilog
+        options_lines.next()  # Drop first line
+
+        def fix_line(line):
+            """
+            Remove indentation and replace curly braces with angle brackets
+            to match the expected format
+            """
+            line = line[2:]
+
+            # Apply changes only to option lines,
+            # not the ones with the help text
+            if line.startswith('-'):
+                line = line.replace('{', '<')
+                line = line.replace('}', '>')
+            return line
+
+        options_lines = [fix_line(line) for line in options_lines]
+        options = '\n'.join(options_lines)
+
+        if parser.epilog is None:
+            epilog = ''
+        else:
+            # Highlight program name and options
+            epilog = parser.epilog % {'prog': '**%s**' % script_name}
+            epilog = re.sub(r'(-\w)', r'**\1**', epilog)
+
+            # Duplicate backslashes to avoid dropping them
+            # because of the rst formatting
+            epilog = re.sub(r'\\', r'\\\\', epilog)
+
+            # Drop 'For example:'
+            epilog = '\n'.join(epilog.splitlines()[1:])
+
+            # Use line blocks to preserve line breaks
+            # Make sure that block is in a separate paragraph
+            epilog = re.sub(r'^\t', '\n| ', epilog, flags=re.M, count=1)
+            epilog = re.sub(r'^\t', '| ', epilog, flags=re.M)
+
+        return description, options, epilog
+
+    module_names = ('client', 'run_install_test', 'run_test_cobbler',
+                    'run_test_vm', 'run_utah_tests')
+    for module_name in module_names:
+        module = __import__(module_name)
+        parser = module.get_parser()
+        if module_name == 'client':
+            script_name = 'utah'
+        else:
+            script_name = '{}.py'.format(module_name)
+        description, options, epilog = get_parser_strings(script_name, parser)
+
+        for section_name in ('description', 'options', 'epilog'):
+            section = locals()[section_name]
+            filename = 'man/{}_{}.txt'.format(module_name, section_name)
+            with open(filename, 'w') as f:
+                f.write(section)
+
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -230,16 +305,17 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('man/utah', 'utah', u'Ubuntu Test Automation Harness',
-     [u'Canonical Ltd'], 1),
-    ('man/run_install_test.py', 'run_install_test.py', u'run_install_test.py',
-     [u'Canonical Ltd'], 1),
-    ('man/run_test_cobbler.py', 'run_test_cobbler.py', u'run_test_cobbler.py',
-     [u'Canonical Ltd'], 1),
-    ('man/run_test_vm.py', 'run_test_vm.py', u'run_test_vm.py',
-     [u'Canonical Ltd'], 1),
-    ('man/run_utah_tests.py', 'run_utah_tests.py', u'run_utah_tests.py',
-     [u'Canonical Ltd'], 1),
+    ('man/utah', 'utah', u'UTAH client test runner',
+     [u'Canonical Ltd'], 1),
+    ('man/run_install_test.py', 'run_install_test.py',
+      u'UTAH server test runner (provisioning)', [u'Canonical Ltd'], 1),
+    ('man/run_test_cobbler.py', 'run_test_cobbler.py',
+     u'UTAH server test runner (physical hardware)', [u'Canonical Ltd'], 1),
+    ('man/run_test_vm.py', 'run_test_vm.py',
+     u'UTAH server test runner (virtual hardware)',
+     [u'Canonical Ltd'], 1),
+    ('man/run_utah_tests.py', 'run_utah_tests.py',
+      u'UTAH server test runner (any hardware)', [u'Canonical Ltd'], 1),
 ]
 
 # If true, show URL addresses after external links.

=== modified file 'docs/source/introduction.rst'
--- docs/source/introduction.rst	2012-08-20 14:54:00 +0000
+++ docs/source/introduction.rst	2012-09-06 07:23:19 +0000
@@ -124,7 +124,7 @@
                             Variant of architecture, i.e., armel, armhf
       -n, --no-destroy      Preserve machine after tests have run
       -d, --debug           Enable debug logging
-      -j, --json            Enable json logging (Default is YAML)
+      -j, --json            Enable json logging (default is YAML)
 
 For example::
 

=== modified file 'docs/source/man/run_install_test.py.rst'
--- docs/source/man/run_install_test.py.rst	2012-09-03 11:05:38 +0000
+++ docs/source/man/run_install_test.py.rst	2012-09-06 07:23:19 +0000
@@ -5,57 +5,19 @@
 
 Synopsis
 --------
-**run_install_test.py** [*options*] [*runlist* ...]
+**run_install_test.py** [options] [runlist ...]
 
 Description
 -----------
-Provision a machine and run one or more UTAH runlists there
+.. include:: run_install_test_description.txt
 
 Options
 -------
--h, --help            show this help message and exit
--m <physical,virtual>, --machinetype <physical,virtual>
-                      Type of machine to provision
--e EMULATOR, --emulator EMULATOR
-                      Emulator to use (kvm and qemu are supported, kvm will
-                      be favored if available)
--i IMAGE, --image IMAGE
-                      Image/ISO file to use for installation
--k KERNEL, --kernel KERNEL
-                      Kernel file to use for installation
--r INITRD, --initrd INITRD
-                      InitRD file to use for installation
--p PRESEED, --preseed PRESEED
-                      Preseed file to use for installation
--b BOOT, --boot BOOT  Boot arguments for initial installation
--x XML, --xml XML     XML VM definition file
--g GIGABYTES, --gigabytes GIGABYTES
-                      Size in gigabytes of virtual disk, specify more than
-                      once for multiple disks
--s <hardy,lucid,natty,oneiric,precise,quantal>, --series <hardy,lucid,natty,oneiric,precise,quantal>
-                      Series to use for installation
--t <desktop,server,mini,alternate>, --type <desktop,server,mini,alternate>
-                      Install type to use for installation
--a <i386,amd64,arm>, --arch <i386,amd64,arm>
-                      Architecture to use for installation
--v VARIANT, --variant VARIANT
-                      Variant of architecture, i.e., armel, armhf
--n, --no-destroy      Preserve machine after tests have run
--d, --debug           Enable debug logging
--j, --json            Enable json logging (Default is YAML)
---diskbus <virtio,sata,ide>
-                      Disk bus to use for customvm installation
---name NAME           Name of machine to provision (currently only supported
-                      for physical machine provisioning)
+.. include:: run_install_test_options.txt
 
 Examples
 --------
-| **run_utah_tests.py** **-s** precise **-t** server **-a** i386 \\
-|     /usr/share/utah/client/examples/master.run \\
-|     'http://people.canonical.com/~max/max_test.run'
-
-Provision a VM using a precise server image i386 architecture and run the two
-given runlists.
+.. include:: run_install_test_epilog.txt
 
 See also
 --------

=== modified file 'docs/source/man/run_test_cobbler.py.rst'
--- docs/source/man/run_test_cobbler.py.rst	2012-09-03 11:09:31 +0000
+++ docs/source/man/run_test_cobbler.py.rst	2012-09-06 07:23:19 +0000
@@ -5,37 +5,19 @@
 
 Synopsis
 --------
-**run_test_cobbler.py** [*options*] [*runlist* ...]
+**run_test_cobbler.py** [options] [runlist ...]
 
 Description
 -----------
-Provision a machine using cobbler and run one or more UTAH runlists there.
+.. include:: run_test_cobbler_description.txt
 
 Options
 -------
--h, --help            show this help message and exit
--n NAME, --name NAME  Name of machine to provision
--i IMAGE, --image IMAGE
-                      Image/ISO file to use for installation
--p PRESEED, --preseed PRESEED
-                      Preseed file to use for installation
--s <hardy,lucid,natty,oneiric,precise,quantal>, --series <hardy,lucid,natty,oneiric,precise,quantal>
-                      Series to use for VM creation
--t <desktop,server,mini,alternate>, --type <desktop,server,mini,alternate>
-                      Install type to use for VM creation
--a <i386,amd64>, --arch <i386,amd64>
-                      Architecture to use for VM creation
--d, --debug           Enable debug logging
--j, --json            Enable json logging (Default is YAML)
+.. include:: run_test_cobbler_options.txt
 
 Examples
 --------
-| **run_test_cobbler.py** **-s** precise **-t** server **-a** i386 \\
-|     /usr/share/utah/client/examples/master.run \\
-|     'http://people.canonical.com/~max/max_test.run'
-
-Provision a machine using a precise server image i386 architecture and run the
-two given runlists.
+.. include:: run_test_cobbler_epilog.txt
 
 See also
 --------

=== modified file 'docs/source/man/run_test_vm.py.rst'
--- docs/source/man/run_test_vm.py.rst	2012-09-03 11:09:31 +0000
+++ docs/source/man/run_test_vm.py.rst	2012-09-06 07:23:19 +0000
@@ -5,33 +5,19 @@
 
 Synopsis
 --------
-run_test_vm.py [**options**] [**runlist** ...]
+**run_test_vm.py** [options] [runlist ...]
 
 Description
 -----------
-Create a virtual machine and run a UTAH runlist there.
+.. include:: run_test_vm_description.txt
 
 Options
 -------
--h, --help            show this help message and exit
--s <hardy,lucid,natty,oneiric,precise,quantal>, --series <hardy,lucid,natty,oneiric,precise,quantal>
-                      Series to use for VM creation
--t <desktop,server,mini,alternate>, --type <desktop,server,mini,alternate>
-                      Install type to use for VM creation
--a <i386,amd64>, --arch <i386,amd64>
-                      Architecture to use for VM creation
--n, --no-destroy      Preserve VM after tests have run
--d, --debug           Enable debug logging
--j, --json            Enable json logging (Default is YAML)
+.. include:: run_test_vm_options.txt
 
 Examples
 --------
-| **run_test_vm.py** **-s** precise **-t** server **-a** i386 \\
-|     /usr/share/utah/client/examples/master.run \\
-|     'http://people.canonical.com/~max/max_test.run'
-
-Provision a VM using a precise server image i386 architecture and run the two
-given runlists.
+.. include:: run_test_vm_epilog.txt
 
 See also
 --------

=== modified file 'docs/source/man/run_utah_tests.py.rst'
--- docs/source/man/run_utah_tests.py.rst	2012-09-03 11:09:31 +0000
+++ docs/source/man/run_utah_tests.py.rst	2012-09-06 07:23:19 +0000
@@ -5,58 +5,19 @@
 
 Synopsis
 --------
-run_utah_tests.py [**options**] [**runlist** ...]
+**run_utah_tests.py** [options] [runlist ...]
 
 Description
 -----------
-Provision a machine using cobbler and run one or more UTAH runlists there.
+.. include:: run_utah_tests_description.txt
 
 Options
 -------
--h, --help            show this help message and exit
--m <physical,virtual>, --machinetype <physical,virtual>
-                      Type of machine to provision
--e EMULATOR, --emulator EMULATOR
-                      Emulator to use (kvm and qemu are supported, kvm will
-                      be favored if available)
--i IMAGE, --image IMAGE
-                      Image/ISO file to use for installation
--k KERNEL, --kernel KERNEL
-                      Kernel file to use for installation
--r INITRD, --initrd INITRD
-                      InitRD file to use for installation
--p PRESEED, --preseed PRESEED
-                      Preseed file to use for installation
--b BOOT, --boot BOOT  Boot arguments for initial installation
--x XML, --xml XML     XML VM definition file
--g GIGABYTES, --gigabytes GIGABYTES
-                      Size in gigabytes of virtual disk, specify more than
-                      once for multiple disks
--s <hardy,lucid,natty,oneiric,precise,quantal>, --series <hardy,lucid,natty,oneiric,precise,quantal>
-                      Series to use for installation
--t <desktop,server,mini,alternate>, --type <desktop,server,mini,alternate>
-                      Install type to use for installation
--a <i386,amd64,arm>, --arch <i386,amd64,arm>
-                      Architecture to use for installation
--v VARIANT, --variant VARIANT
-                      Variant of architecture, i.e., armel, armhf
--n, --no-destroy      Preserve machine after tests have run
--d, --debug           Enable debug logging
--j, --json            Enable json logging (Default is YAML)
---diskbus <virtio,sata,ide>
-                      Disk bus to use for customvm installation
---name NAME           Name of machine to provision (currently only supported
-                      for physical machine provisioning)
-
+.. include:: run_utah_tests_options.txt
 
 Examples
 --------
-| **run_utah_tests.py** **-s** precise **-t** server **-a** i386 \\
-|     /usr/share/utah/client/examples/master.run \\
-|     'http://people.canonical.com/~max/max_test.run'
-
-Provision a VM using a precise server image i386 architecture and run the two
-given runlists.
+.. include:: run_utah_tests_epilog.txt
 
 See also
 --------

=== modified file 'docs/source/man/utah.rst'
--- docs/source/man/utah.rst	2012-09-03 10:42:26 +0000
+++ docs/source/man/utah.rst	2012-09-06 07:23:19 +0000
@@ -5,28 +5,12 @@
 
 Synopsis
 --------
-
 **utah** [options]
 
 Description
 -----------
-
-:program:`utah` executes a runlist and generates a file with the results
+.. include:: client_description.txt
 
 Options
 -------
--h, --help            show this help message and exit
---resume              Continue a previous run. Used after a reboot
--s STATE_FILE, --state-file STATE_FILE
-                      File to use for storing state (default
-                      "/var/lib/utah/state.yaml")
--f <text,yaml,json>, --format <text,yaml,json>
-                      Output format (default "yaml")
--t TESTDIR, --testdir TESTDIR
-                      Main test directory
--r RUNLIST, --runlist RUNLIST
-                      runlist file name
--o OUTPUT, --output OUTPUT
-                      write output to this file
--a, --append          append to output
--d, --debug           Print debugging output
+.. include:: client_options.txt

=== modified file 'examples/run_install_test.py'
--- examples/run_install_test.py	2012-08-20 20:56:16 +0000
+++ examples/run_install_test.py	2012-09-06 07:23:19 +0000
@@ -16,14 +16,17 @@
             description=('Provision a machine '
                          'and run one or more UTAH runlists there.'),
             epilog=("For example:\n"
-                    "\t%(prog)s -s precise -t server -a i386 "
-                    "/usr/share/utah/client/examples/master.run "
-                    "'http://people.canonical.com/~max/max_test.run'"),
+                    "Provision a VM using a precise server image "
+                    "with i386 architecture and run the two given runlists\n"
+                    "\t%(prog)s -s precise -t server -a i386 \\\n"
+                    "\t\t/usr/share/utah/client/examples/master.run \\\n"
+                    "\t\t'http://people.canonical.com/~max/max_test.run'"),
             formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument('runlists', metavar='runlist', nargs='+',
                         type=url_argument, help='URLs of runlist files to run')
-    parser.add_argument('-m', '--machinetype', choices=('physical', 'virtual'),
-                        default='virtual', help='Type of machine to provision')
+    parser.add_argument('-m', '--machinetype', metavar='MACHINETYPE',
+                        choices=('physical', 'virtual'), default='virtual',
+                        help='Type of machine to provision (%(choices)s)')
     parser.add_argument('-e', '--emulator',
                         help=('Emulator to use (kvm and qemu are supported, '
                               'kvm will be favored if available)'))
@@ -42,15 +45,18 @@
     parser.add_argument('-g', '--gigabytes', action='append',
                         help=('Size in gigabytes of virtual disk, '
                               'specify more than once for multiple disks'))
-    parser.add_argument('-s', '--series',
+    parser.add_argument('-s', '--series', metavar='SERIES',
                         choices=('hardy', 'lucid', 'natty',
                                  'oneiric', 'precise', 'quantal'),
-                        help='Series to use for installation')
-    parser.add_argument('-t', '--type',
+                        help='Series to use for installation (%(choices)s)')
+    parser.add_argument('-t', '--type', metavar='TYPE',
                         choices=('desktop', 'server', 'mini', 'alternate'),
-                        help='Install type to use for installation')
-    parser.add_argument('-a', '--arch', choices=('i386', 'amd64', 'arm'),
-                        help='Architecture to use for installation')
+                        help=('Install type to use for installation '
+                              '(%(choices)s)'))
+    parser.add_argument('-a', '--arch', metavar='ARCH',
+                        choices=('i386', 'amd64', 'arm'),
+                        help=('Architecture to use for installation '
+                              '(%(choices)s)'))
     parser.add_argument('-v', '--variant',
                         help='Variant of architecture, i.e., armel, armhf')
     parser.add_argument('-n', '--no-destroy', action='store_true',
@@ -58,9 +64,11 @@
     parser.add_argument('-d', '--debug', action='store_true',
                         help='Enable debug logging')
     parser.add_argument('-j', '--json', action='store_true',
-                        help='Enable json logging (Default is YAML)')
-    parser.add_argument('--diskbus', choices=('virtio', 'sata', 'ide'),
-                        help='Disk bus to use for customvm installation')
+                        help='Enable json logging (default is YAML)')
+    parser.add_argument('--diskbus', metavar='DISKBUS',
+                        choices=('virtio', 'sata', 'ide'),
+                        help=('Disk bus to use for customvm installation '
+                              '(%(choices)s)'))
     return parser
 
 

=== modified file 'examples/run_test_cobbler.py'
--- examples/run_test_cobbler.py	2012-08-20 21:06:59 +0000
+++ examples/run_test_cobbler.py	2012-09-06 07:23:19 +0000
@@ -16,9 +16,11 @@
             description=('Provision a machine using cobbler '
                          'and run one or more UTAH runlists there.'),
             epilog=("For example:\n"
-                    "\t%(prog)s -s precise -t server -a i386 "
-                    "/usr/share/utah/client/examples/master.run "
-                    "'http://people.canonical.com/~max/max_test.run'"),
+                    "Provision a machine using a precise server image "
+                    "with i386 architecture and run the two given runlists\n"
+                    "\t%(prog)s -s precise -t server -a i386 \\\n"
+                    "\t\t/usr/share/utah/client/examples/master.run \\\n"
+                    "\t\t'http://people.canonical.com/~max/max_test.run'"),
             formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument('runlists', metavar='runlist', nargs='+',
                         help='URLs of runlist files to run')
@@ -27,19 +29,22 @@
                         help='Image/ISO file to use for installation')
     parser.add_argument('-p', '--preseed', type=url_argument,
                         help='Preseed file to use for installation')
-    parser.add_argument('-s', '--series',
+    parser.add_argument('-s', '--series', metavar='SERIES',
                         choices=('hardy', 'lucid', 'natty',
                                  'oneiric', 'precise', 'quantal'),
-                        help='Series to use for VM creation')
-    parser.add_argument('-t', '--type',
+                        help='Series to use for VM creation (%(choices)s)')
+    parser.add_argument('-t', '--type', metavar='TYPE',
                         choices=('desktop', 'server', 'mini', 'alternate'),
-                        help='Install type to use for VM creation')
-    parser.add_argument('-a', '--arch', choices=('i386', 'amd64'),
-                        help='Architecture to use for VM creation')
+                        help=('Install type to use for VM creation '
+                              '(%(choices)s)'))
+    parser.add_argument('-a', '--arch', metavar='ARCH',
+                        choices=('i386', 'amd64'),
+                        help=('Architecture to use for VM creation '
+                              '(%(choices)s)'))
     parser.add_argument('-d', '--debug', action='store_true',
                         help='Enable debug logging')
     parser.add_argument('-j', '--json', action='store_true',
-                        help='Enable json logging (Default is YAML)')
+                        help='Enable json logging (default is YAML)')
     return parser
 
 

=== modified file 'examples/run_test_vm.py'
--- examples/run_test_vm.py	2012-08-20 21:00:06 +0000
+++ examples/run_test_vm.py	2012-09-06 07:23:19 +0000
@@ -14,27 +14,32 @@
             description=('Create a virtual machine '
                          'and run a UTAH runlist there.'),
             epilog=("For example:\n"
-                    "\t%(prog)s -s precise -t server -a i386 "
-                    "/usr/share/utah/client/examples/master.run "
-                    "'http://people.canonical.com/~max/max_test.run'"),
+                    "Provision a VM using a precise server image "
+                    "with i386 architecture and run the two given runlists\n"
+                    "\t%(prog)s -s precise -t server -a i386 \\\n"
+                    "\t\t/usr/share/utah/client/examples/master.run \\\n"
+                    "\t\t'http://people.canonical.com/~max/max_test.run'"),
             formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument('runlists', metavar='runlist', nargs='+',
                         help='URLs of runlist files to run')
-    parser.add_argument('-s', '--series',
+    parser.add_argument('-s', '--series', metavar='SERIES',
                         choices=('hardy', 'lucid', 'natty',
                                  'oneiric', 'precise', 'quantal'),
-                        help='Series to use for VM creation')
-    parser.add_argument('-t', '--type',
+                        help='Series to use for VM creation (%(choices)s)')
+    parser.add_argument('-t', '--type', metavar='TYPE',
                         choices=('desktop', 'server', 'mini', 'alternate'),
-                        help='Install type to use for VM creation')
-    parser.add_argument('-a', '--arch', choices=('i386', 'amd64'),
-                        help='Architecture to use for VM creation')
+                        help=('Install type to use for VM creation '
+                              '(%(choices)s)'))
+    parser.add_argument('-a', '--arch', metavar='ARCH',
+                        choices=('i386', 'amd64'),
+                        help=('Architecture to use for VM creation '
+                              '(%(choices)s)'))
     parser.add_argument('-n', '--no-destroy', action='store_true',
                         help='Preserve VM after tests have run')
     parser.add_argument('-d', '--debug', action='store_true',
                         help='Enable debug logging')
     parser.add_argument('-j', '--json', action='store_true',
-                        help='Enable json logging (Default is YAML)')
+                        help='Enable json logging (default is YAML)')
     return parser
 
 

=== modified file 'examples/run_utah_tests.py'
--- examples/run_utah_tests.py	2012-08-14 15:42:17 +0000
+++ examples/run_utah_tests.py	2012-09-06 07:23:19 +0000
@@ -15,14 +15,17 @@
             description=('Provision a machine '
                          'and run one or more UTAH runlists there.'),
             epilog=("For example:\n"
-                    "\t%(prog)s -s precise -t server -a i386 "
-                    "/usr/share/utah/client/examples/master.run "
-                    "'http://people.canonical.com/~max/max_test.run'"),
+                    "Provision a VM using a precise server image "
+                    "with i386 architecture and run the two given runlists\n"
+                    "\t%(prog)s -s precise -t server -a i386 \\\n"
+                    "\t\t/usr/share/utah/client/examples/master.run \\\n"
+                    "\t\t'http://people.canonical.com/~max/max_test.run'"),
             formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument('runlists', metavar='runlist', nargs='+',
                         type=url_argument, help='URLs of runlist files to run')
-    parser.add_argument('-m', '--machinetype', choices=('physical', 'virtual'),
-                        default='virtual', help='Type of machine to provision')
+    parser.add_argument('-m', '--machinetype', metavar='MACHINETYPE',
+                        choices=('physical', 'virtual'), default='virtual',
+                        help='Type of machine to provision (%(choices)s)')
     parser.add_argument('-e', '--emulator',
                         help=('Emulator to use (kvm and qemu are supported, '
                               'kvm will be favored if available)'))
@@ -41,15 +44,18 @@
     parser.add_argument('-g', '--gigabytes', action='append',
                         help=('Size in gigabytes of virtual disk, '
                               'specify more than once for multiple disks'))
-    parser.add_argument('-s', '--series',
+    parser.add_argument('-s', '--series', metavar='SERIES',
                         choices=('hardy', 'lucid', 'natty',
                                  'oneiric', 'precise', 'quantal'),
-                        help='Series to use for installation')
-    parser.add_argument('-t', '--type',
+                        help='Series to use for installation (%(choices)s)')
+    parser.add_argument('-t', '--type', metavar='TYPE',
                         choices=('desktop', 'server', 'mini', 'alternate'),
-                        help='Install type to use for installation')
-    parser.add_argument('-a', '--arch', choices=('i386', 'amd64', 'arm'),
-                        help='Architecture to use for installation')
+                        help=('Install type to use for installation '
+                              '(%(choices)s)'))
+    parser.add_argument('-a', '--arch', metavar='ARCH',
+                        choices=('i386', 'amd64', 'arm'),
+                        help=('Architecture to use for installation '
+                              '(%(choices)s)'))
     parser.add_argument('-v', '--variant',
                         help='Variant of architecture, i.e., armel, armhf')
     parser.add_argument('-n', '--no-destroy', action='store_true',
@@ -57,9 +63,11 @@
     parser.add_argument('-d', '--debug', action='store_true',
                         help='Enable debug logging')
     parser.add_argument('-j', '--json', action='store_true',
-                        help='Enable json logging (Default is YAML)')
-    parser.add_argument('--diskbus', choices=('virtio', 'sata', 'ide'),
-                        help='Disk bus to use for customvm installation')
+                        help='Enable json logging (default is YAML)')
+    parser.add_argument('--diskbus', metavar='DISKBUS',
+                        choices=('virtio', 'sata', 'ide'),
+                        help=('Disk bus to use for customvm installation '
+                              '(%(choices)s)'))
     parser.add_argument('--name', help='Name of machine to provision'
                         + ' (currently only supported for physical machine'
                         + ' provisioning)')