Merge lp:~utah/utah/bug1039555 into lp:utah

[Javier Collado]

This branch adds manual pages for both the server and the client packages.

The packaging changes have been already reviewed when merging other branches to this one, so the final thing to be reviewed before merging to dev, should be just the text for the manual pages which is autogenerated from the parser objects in the code.

To review this, please follow these steps:
bzr branch lp:~utah/utah/bug1039555
make manpages
man ./docs/build/man/<script>.1

where <script> is any of the scripts in both the client and server packages.

[Max Brustkern (nuclearbob)]

This looks good to me.

review: Approve

[Gema Gomez (gema)]

The run_utah_tests documentation could do with some explaining on how it uses the other scripts.

The utah document needs a bit more of description, explicitely saying that is only intended to be used for development purposes or when the machine targetted for the testing is the current development machine, that otherwise it'll be used by run_utah_tests after provisioning the test environment.

Other than that I like the documents a lot, please make sure to explain max and joe how to keep them up to date.

review: Approve

[lp:~utah/utah/bug1039555]

664. By Javier Collado on 2012-09-14

Updated description to describe what the client actually does

665. By Javier Collado on 2012-09-14

Added note to make clear that run_utah_tests is a wrapper around the other scripts

666. By Javier Collado on 2012-09-14

Added note to describe when `utah` should be used

=== modified file 'Makefile'
--- Makefile	2012-08-14 16:42:41 +0000
+++ Makefile	2012-09-14 11:09:20 +0000
@@ -1,5 +1,5 @@
 PYC_PATTERN?=*.pyc
-all: client conf/utah/bootspeed-preseed.cfg conf/utah/bridged-network-vm.xml conf/utah/config
+all: client conf/utah/bootspeed-preseed.cfg conf/utah/bridged-network-vm.xml conf/utah/config manpages
 
 client:
 	[ -d "client" ] || mkdir client
@@ -17,6 +17,9 @@
 conf/utah/config:
 	./utah/config.py > conf/utah/config
 
+manpages:
+	cd docs && make man
+
 clean:
 	find . -name "$(PYC_PATTERN)" -delete
 	rm -rf client
@@ -25,5 +28,6 @@
 	rm -f utah/config
 	rm -f utah_*
 	rm -f utah-*
+	cd docs && make clean
 
-.PHONY: client clean
+.PHONY: client clean manpages
 
=== modified file 'client-Makefile'
--- client-Makefile	2012-05-21 14:05:50 +0000
+++ client-Makefile	2012-09-14 11:09:20 +0000
@@ -1,4 +1,4 @@
-all: utah-client_fake_all.deb utah/config
+all: utah-client_fake_all.deb utah/config manpages
 
 utah-client_fake_all.deb:
 	touch utah-client_fake_all.deb
@@ -6,7 +6,11 @@
 utah/config:
 	touch utah/config
 
+manpages:
+	cd docs && make man
+
 clean:
 	rm utah/config
+	cd docs && make clean
 
-.PHONY: clean
+.PHONY: clean manpages
 
=== modified file 'client.py'
--- client.py	2012-08-31 09:25:38 +0000
+++ client.py	2012-09-14 11:09:20 +0000
@@ -14,23 +14,28 @@
 from utah.client.exceptions import UTAHClientError
 
 
-def process_cmdline_argparse():
+def get_parser():
     """
     Process the command line arguments.
     """
-
     # requires Python2.7+
     import argparse
 
     parser = argparse.ArgumentParser(
-            description='Ubuntu Automation Testing Harness')
+        description='''Run test cases locally and write results to a file.
+
+Note: This is expected to be used only for development purposes on a machine
+that has been provisioned using run_utah_tests.py''',
+        formatter_class=argparse.RawTextHelpFormatter)
     parser.add_argument('--resume', action='store_true',
                         help='Continue a previous run.  Used after a reboot')
     parser.add_argument('-s', '--state-file',
-                        help=('File to use for storing state (default "%s"'
+                        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('-i', '--install-type',
@@ -49,13 +54,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):
@@ -77,7 +76,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 'debian/control'
--- debian/control	2012-09-13 12:41:29 +0000
+++ debian/control	2012-09-14 11:09:20 +0000
@@ -3,7 +3,11 @@
 X-Python-Version: >= 2.5
 Priority: optional
 Maintainer: Max Brustkern <[e-mail]>
+<<<<<<< TREE
 Build-Depends: debhelper (>= 7.0.50~), devscripts, python-all
+=======
+Build-Depends: debhelper (>= 7.0.50~), devscripts, python-all, python-sphinx
+>>>>>>> MERGE-SOURCE
 Standards-Version: 3.9.3
 Homepage: https://code.launchpad.net/utah
 Vcs-Bzr: https://code.launchpad.net/utah
 
=== modified file 'debian/rules'
--- debian/rules	2012-08-17 09:47:01 +0000
+++ debian/rules	2012-09-14 11:09:20 +0000
@@ -47,3 +47,6 @@
 		fi;\
 	done
 	dh_auto_install
+
+override_dh_installman:
+	dh_installman --language=C
 
=== added file 'debian/utah-client.manpages'
--- debian/utah-client.manpages	1970-01-01 00:00:00 +0000
+++ debian/utah-client.manpages	2012-09-14 11:09:20 +0000
@@ -0,0 +1,1 @@
+docs/build/man/utah.1
 
=== added file 'debian/utah.manpages'
--- debian/utah.manpages	1970-01-01 00:00:00 +0000
+++ debian/utah.manpages	2012-09-14 11:09:20 +0000
@@ -0,0 +1,4 @@
+docs/build/man/run_install_test.py.1
+docs/build/man/run_test_cobbler.py.1
+docs/build/man/run_test_vm.py.1
+docs/build/man/run_utah_tests.py.1
 
=== modified file 'docs/Makefile'
--- docs/Makefile	2012-08-07 16:06:37 +0000
+++ docs/Makefile	2012-09-14 11:09:20 +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-06 15:44:36 +0000
+++ docs/source/conf.py	2012-09-14 11:09:20 +0000
@@ -12,13 +12,20 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+<<<<<<< TREE
 import sys
 import os
+=======
+import sys, os
+import itertools
+import re
+>>>>>>> MERGE-SOURCE
 
 # 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 ModuleMock(object):
@@ -64,14 +71,96 @@
                  'apt', 'apt.cache'):
     sys.modules[mod_name] = ModuleMock(mod_name)
 
+<<<<<<< TREE
 # -- General configuration ----------------------------------------------------
+=======
+
+# 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 -----------------------------------------------------
+>>>>>>> MERGE-SOURCE
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
+<<<<<<< TREE
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc']
+=======
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+>>>>>>> MERGE-SOURCE
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -261,8 +350,17 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'utah', u'UTAH Documentation',
-     [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-14 11:09:20 +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::
 
 
=== added directory 'docs/source/man'
=== added file 'docs/source/man/run_install_test.py.rst'
--- docs/source/man/run_install_test.py.rst	1970-01-01 00:00:00 +0000
+++ docs/source/man/run_install_test.py.rst	2012-09-14 11:09:20 +0000
@@ -0,0 +1,26 @@
+:orphan:
+
+run_install_test.py manual page
+===============================
+
+Synopsis
+--------
+**run_install_test.py** [options] [runlist ...]
+
+Description
+-----------
+.. include:: run_install_test_description.txt
+
+Options
+-------
+.. include:: run_install_test_options.txt
+
+Examples
+--------
+.. include:: run_install_test_epilog.txt
+
+See also
+--------
+:manpage:`run_test_cobbler.py(1)`
+:manpage:`run_test_vm.py(1)`
+:manpage:`run_utah_tests.py(1)`
 
=== added file 'docs/source/man/run_test_cobbler.py.rst'
--- docs/source/man/run_test_cobbler.py.rst	1970-01-01 00:00:00 +0000
+++ docs/source/man/run_test_cobbler.py.rst	2012-09-14 11:09:20 +0000
@@ -0,0 +1,26 @@
+:orphan:
+
+run_test_cobbler.py manual page
+===============================
+
+Synopsis
+--------
+**run_test_cobbler.py** [options] [runlist ...]
+
+Description
+-----------
+.. include:: run_test_cobbler_description.txt
+
+Options
+-------
+.. include:: run_test_cobbler_options.txt
+
+Examples
+--------
+.. include:: run_test_cobbler_epilog.txt
+
+See also
+--------
+:manpage:`run_install_test.py(1)`
+:manpage:`run_test_vm.py(1)`
+:manpage:`run_utah_tests.py(1)`
 
=== added file 'docs/source/man/run_test_vm.py.rst'
--- docs/source/man/run_test_vm.py.rst	1970-01-01 00:00:00 +0000
+++ docs/source/man/run_test_vm.py.rst	2012-09-14 11:09:20 +0000
@@ -0,0 +1,26 @@
+:orphan:
+
+run_test_vm.py manual page
+==========================
+
+Synopsis
+--------
+**run_test_vm.py** [options] [runlist ...]
+
+Description
+-----------
+.. include:: run_test_vm_description.txt
+
+Options
+-------
+.. include:: run_test_vm_options.txt
+
+Examples
+--------
+.. include:: run_test_vm_epilog.txt
+
+See also
+--------
+:manpage:`run_install_test.py(1)`
+:manpage:`run_test_cobbler.py(1)`
+:manpage:`run_utah_tests.py(1)`
 
=== added file 'docs/source/man/run_utah_tests.py.rst'
--- docs/source/man/run_utah_tests.py.rst	1970-01-01 00:00:00 +0000
+++ docs/source/man/run_utah_tests.py.rst	2012-09-14 11:09:20 +0000
@@ -0,0 +1,26 @@
+:orphan:
+
+run_utah_tests.py manual page
+==============================
+
+Synopsis
+--------
+**run_utah_tests.py** [options] [runlist ...]
+
+Description
+-----------
+.. include:: run_utah_tests_description.txt
+
+Options
+-------
+.. include:: run_utah_tests_options.txt
+
+Examples
+--------
+.. include:: run_utah_tests_epilog.txt
+
+See also
+--------
+:manpage:`run_install_test.py(1)`
+:manpage:`run_test_cobbler.py(1)`
+:manpage:`run_test_vm.py(1)`
 
=== added file 'docs/source/man/utah.rst'
--- docs/source/man/utah.rst	1970-01-01 00:00:00 +0000
+++ docs/source/man/utah.rst	2012-09-14 11:09:20 +0000
@@ -0,0 +1,16 @@
+:orphan:
+
+utah manual page
+================
+
+Synopsis
+--------
+**utah** [options]
+
+Description
+-----------
+.. include:: client_description.txt
+
+Options
+-------
+.. 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-14 11:09:20 +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-30 08:34:34 +0000
+++ examples/run_test_cobbler.py	2012-09-14 11:09:20 +0000
@@ -15,9 +15,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')
@@ -26,19 +28,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-14 11:09:20 +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-30 08:35:45 +0000
+++ examples/run_utah_tests.py	2012-09-14 11:09:20 +0000
@@ -13,16 +13,21 @@
 def get_parser():
     parser = argparse.ArgumentParser(
             description=('Provision a machine '
-                         'and run one or more UTAH runlists there.'),
+                         'and run one or more UTAH runlists there.\n\n'
+                         'The appropriate run_*.py script will be called, '
+                         'depending on the parameters passed.'),
             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 +46,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 +65,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)')
 
=== modified file 'utah_howto.txt'
--- utah_howto.txt	2012-08-02 14:18:50 +0000
+++ utah_howto.txt	2012-09-14 11:09:20 +0000
@@ -60,7 +60,7 @@
 usage: utah [-h] [--resume] [-s STATE_FILE] [-f {text,yaml}] [-t TESTDIR]
             [-r RUNLIST] [-o OUTPUT] [-a] [-d]
 
-Ubuntu Automation Testing Harness
+Ubuntu Testing Automation Harness
 
 optional arguments:
   -h, --help            show this help message and exit