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

[Javier Collado]

This branch contains the manual pages for the server package.

The text isn't the final one. For this merge, I'm interested just in reviewing the packaging changes to get the man pages installed.

Also, aside from the final text, I'll take a look at how to autogenerate the options section from the argparse code in a separate branch.

[Javier Collado (javier.collado)]

A new branch has been created to autogenerate manual pages contents from the scripts parser objects:
lp:~javier.collado/utah/bug1039555-autogenerate

As explained above, just focus on the packaging since the text in the man page isn't the final one.

[Max Brustkern (nuclearbob)]

Seems reasonable to me.

review: Approve

=== modified file 'client.py'
--- client.py	2012-08-22 16:42:35 +0000
+++ client.py	2012-09-03 11:19:25 +0000
@@ -27,7 +27,7 @@
     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")')

=== modified file 'debian/rules'
--- debian/rules	2012-08-17 09:47:01 +0000
+++ debian/rules	2012-09-03 11:19:25 +0000
@@ -47,3 +47,6 @@
 		fi;\
 	done
 	dh_auto_install
+
+override_dh_installman:
+	dh_installman --language=C

=== added file 'debian/utah.manpages'
--- debian/utah.manpages	1970-01-01 00:00:00 +0000
+++ debian/utah.manpages	2012-09-03 11:19:25 +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/source/conf.py'
--- docs/source/conf.py	2012-08-22 16:42:35 +0000
+++ docs/source/conf.py	2012-09-03 11:19:25 +0000
@@ -231,7 +231,15 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('man/utah', 'utah', u'Ubuntu Test Automation Harness',
-     [u'Canonical Ltd'], 1)
+     [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),
 ]
 
 # If true, show URL addresses after external links.

=== 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-03 11:19:25 +0000
@@ -0,0 +1,64 @@
+:orphan:
+
+run_install_test.py manual page
+===============================
+
+Synopsis
+--------
+**run_install_test.py** [*options*] [*runlist* ...]
+
+Description
+-----------
+Provision a machine and run one or more UTAH runlists there
+
+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)
+
+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.
+
+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-03 11:19:25 +0000
@@ -0,0 +1,44 @@
+:orphan:
+
+run_test_cobbler.py manual page
+===============================
+
+Synopsis
+--------
+**run_test_cobbler.py** [*options*] [*runlist* ...]
+
+Description
+-----------
+Provision a machine using cobbler and run one or more UTAH runlists there.
+
+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)
+
+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.
+
+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-03 11:19:25 +0000
@@ -0,0 +1,40 @@
+:orphan:
+
+run_test_vm.py manual page
+==========================
+
+Synopsis
+--------
+run_test_vm.py [**options**] [**runlist** ...]
+
+Description
+-----------
+Create a virtual machine and run a UTAH runlist there.
+
+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)
+
+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.
+
+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-03 11:19:25 +0000
@@ -0,0 +1,65 @@
+:orphan:
+
+run_utah_tests.py manual page
+==============================
+
+Synopsis
+--------
+run_utah_tests.py [**options**] [**runlist** ...]
+
+Description
+-----------
+Provision a machine using cobbler and run one or more UTAH runlists there.
+
+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)
+
+
+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.
+
+See also
+--------
+:manpage:`run_install_test.py(1)`
+:manpage:`run_test_cobbler.py(1)`
+:manpage:`run_test_vm.py(1)`

=== modified file 'docs/source/man/utah.rst'
--- docs/source/man/utah.rst	2012-08-22 11:32:48 +0000
+++ docs/source/man/utah.rst	2012-09-03 11:19:25 +0000
@@ -6,7 +6,7 @@
 Synopsis
 --------
 
-utah [-h] [--resume] [-s STATE_FILE] [-f {text,yaml,json}] [-t TESTDIR] [-r RUNLIST] [-o OUTPUT] [-a] [-d]
+**utah** [options]
 
 Description
 -----------
@@ -19,7 +19,7 @@
 --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"
+                      "/var/lib/utah/state.yaml")
 -f <text,yaml,json>, --format <text,yaml,json>
                       Output format (default "yaml")
 -t TESTDIR, --testdir TESTDIR