Merge lp:~joetalbott/utah/docs_update_for_phoenix into lp:utah

[Joe Talbott]

Cleanup the documentation a bit and add some phoenix instructions.

[Max Brustkern (nuclearbob)]

Looks good to me.

review: Approve

[Javier Collado (javier.collado)]

To have the source code boxes with the phoenix example, end the sentence with two colons (::) instead of just one (:). There are few examples in the document itself.

Did you want to apply some emphasis to the words between single quotes? If that's the case, then use either stars (**bold**) or double backquotes (``fixed width``).

review: Needs Fixing

[lp:~joetalbott/utah/docs_update_for_phoenix]

714. By Joe Talbott on 2012-10-18

Fix some markup mistakes.

Pointed-Out-By: jcollado

[Joe Talbott (joetalbott)]

Good catch. Fixed.

review: Needs Resubmitting

[Javier Collado (javier.collado)]

@Joe

Thanks for updating the markup.

There are still a few single quotes in the last paragraph that starts with "The
only required fields are". I guess you'll want to update them as well to be
consistent with the previous section.

Also, "Include_tests" and "Exclude_tests" are capitalized, I think I'd keep the
same case as in the yaml file for the sake of clarity.

review: Needs Fixing

[Javier Collado (javier.collado)]

Just to make sure that we look at the same html, the steps I follow are:
- cd docs
- make html
- open docs/build/html/index.html

When working on the source code, vim provides good highlighting for .rst files
(I'm not sure about other editors).

[lp:~joetalbott/utah/docs_update_for_phoenix]

715. By Joe Talbott on 2012-10-19

Fix markup

[Joe Talbott (joetalbott)]

Should be fixed now. I'm getting errors in the 'make html' step so I can't confirm the output locally.

review: Needs Resubmitting

[Javier Collado (javier.collado)]

@Joe

Yes, looks good to me now. Thanks.

review: Approve

=== modified file 'docs/source/development.rst'
--- docs/source/development.rst	2012-10-10 14:44:00 +0000
+++ docs/source/development.rst	2012-10-19 16:46:21 +0000
@@ -1,4 +1,4 @@
-Cool, and how do I start developing for it?
+How do I start developing for it?
 ===========================================
 
 Ubuntu Test Automation Harness will allow developers to quickly and reliably
@@ -39,19 +39,33 @@
 
 This is what a UTAH test suite looks like::
 
-    .
-    |-- testsuite1
-    |   |-- testcase1
-    |   |   |-- Makefile
-    |   |   |-- t1.c
-    |   |   `-- tc_control
-    |   |-- testcase2
-    |   |   |-- test.py
-    |   |   `-- tc_control
-    |   |-- ts_control
-    |   `-- tslist.run
-    |-- testsuite2
-    |-- master.run
+   testsuite1/
+     tslist.run
+     ts_control
+     testcase1/
+       tc_control
+       Makefile
+       test.c
+     testcase2/
+       tc_control
+       test.py
+
+Phoenix - A tool for creating testsuite and testcase skeletons.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Part of the ``utah-client`` is ``phoenix`` which makes getting started creating testsuites a bit easier.  It can be used like this::
+
+    phoenix example_testsuite example1 example2
+
+This creates a testsuite directory ``example_testsuite`` in the current directory with two testcase directories ``example1`` and ``example2`` inside.  In addition a tslist.run, ts_control, and tc_control files for each testcase.  A master.run file is created as well to aid in development.  NOTE: the master.run file will generally be written by a person wishing to run a set of testsuites and/or testcases and will not be a part of a testsuite.
+
+To add a testcase to an existing testsuite::
+
+    phoenix example_testsuite example3
+
+This will add an ``example3`` testcase directory to the example_testsuite testsuite as well as adding an entry to the testsuite's tslist.run.  From within a testsuite directory this can be shortened to::
+
+    phoenix . example3
 
 Runlists Hierarchy
 ~~~~~~~~~~~~~~~~~~
@@ -63,7 +77,7 @@
 ::
 
     - name: testsuite1
-      fetch_method : git
+      fetch_method: git
       fetch_location: repo
       include_tests:
         - t1
@@ -71,15 +85,17 @@
         - t3...
 
     - name: testsuite2
+      fetch_method: bzr
+      fetch_location: lp:utah/dev/
       exclude_tests:
         - st4
         - st5
 
-The only required fields are 'name', 'fetch_method' and 'fetch_location'.  'Name' must correspond to the name of the top-level testsuite directory.  'Fetch_method' should be one of 'bzr', 'bzr-export', or 'git'.  'Fetch_location' should be a valid location for the supplied 'fetch_method'.  If 'bzr' is selected as the fetch method then 'fetch_location' should point to a repository that is a valid testsuite, i.e. has a tslist.run, ts_control (if needed), and test case directories.  While 'bzr' does a 'bzr branch' in the implementation, 'bzr-export' does a 'bzr export' and accepts a bzr location that can point to a sub-directory within a repository that is a valid testsuite. 
-
-One caveat to note is that a 'fetch_method' of 'bzr' will get the revision information from the local copy of the branched repository but 'bzr-export' will have a small race condition between the 'get' and 'revision' calls since the actual bzr repository must be queried for the revision.
-
-'Include_tests' will limit the testcases that are run to only those listed by this option.  'Exclude_tests' will run all the tests in the testsuite's tslist.run file except those listed by this option.
+The only required fields are ``name``, ``fetch_method`` and ``fetch_location``.  ``name`` must correspond to the name of the top-level testsuite directory.  ``fetch_method`` should be one of ``bzr``, ``bzr-export``, or ``git``.  ``fetch_location`` should be a valid location for the supplied ``fetch_method``.  If ``bzr`` is selected as the fetch method then ``fetch_location`` should point to a repository that is a valid testsuite, i.e. has a tslist.run, ts_control (if needed), and test case directories.  While ``bzr`` does a ``bzr branch`` in the implementation, ``bzr-export`` does a ``bzr export`` and accepts a bzr location that can point to a sub-directory within a repository that is a valid testsuite. 
+
+One caveat to note is that a ``fetch_method`` of ``bzr`` will get the revision information from the local copy of the branched repository but ``bzr-export`` will have a small race condition between the ``get`` and ``revision`` calls since the actual bzr repository must be queried for the revision.
+
+``include_tests`` will limit the testcases that are run to only those listed by this option.  ``exclude_tests`` will run all the tests in the testsuite's tslist.run file except those listed by this option.
 
 Test suites can be divided in categories (for our internal use, or for test
 cases submitted to our test case base) or they can be in a repository anywhere.
@@ -119,11 +135,7 @@
    called *sample_tests* and the entry in ``tslist.run`` for test is *test_one*
    then the path to the test folder will be *sample_tests/test_one*.
 
- * ``tslist.run``'s **command** is relative to the testcase’s folder. So the
-   above test with a **command** of ``python test_one.py`` will result in this
-   effectively::
-
-       cd sample_tests/test_one && python test_one.py
+ * ``tslist.run``'s **overrides** are the same options available in the ``tc_control`` file and take precedence over those found in ``tc_control``.
 
  * ``ts_control`` is optional.
  * if ``build_cmd``, or ``ts_setup`` fails no tests in the suite will be run.
@@ -134,7 +146,7 @@
    the test fails.
 
 Each test case, with all the code required for it to compile or run, lives in a
-folder, and contains also a control file that **includes its documentation**
+directory, and contains also a control file that **includes its documentation**
 amongst other things:
 
 **tc_control file contains:**
@@ -144,15 +156,14 @@
     build_cmd:      make    # or scons or build.sh
     command: python test1.py a1 a2 a3  # command to run the test from within t1
     description:
-    ( tc_id: TC-INSTALL-ALTERNATE-01)
-     dependencies:
+     dependencies: coreutils
      actions: |
        1. Action 1
        2. Action 2
      expected_results: |
        1. Expected result 1
        2. Expected result 2
-    type:           build_only/userland/kernel (?)
+    type:           userland/kernel    # currently unimplemented
     timeout:        100
     tc_setup:       t1/t1 setup    # in case the test case has a setup
     tc_cleanup:     t1/t1 cleanup  # in case the test has a cleanup
@@ -169,11 +180,7 @@
 that the harness can run their setup and clean up functions.
 
 **In terms of settings precedence:**
-The test suite control file provides a default value for all the test cases in
-the test suite. Each test case can override those settings in its own control
-file.  The overrides in the suite level runlist override both of them (the idea
-behind being to be able to set up different timeouts depending on the
-architecture the tests ought to be run on, if necessary).
+The test case control file (``tc_control``) provides the default values for the options available for the testcase.  The **overrides** in ``tslist.run`` take precedence over those options in the ``tc_control`` file.
 
 How to use custom preseeds
 --------------------------