Merge lp:~joetalbott/utah/utah-dev_doc-updates into lp:utah

[Joe Talbott]

Update the documentation a bit.

Adds a FAQ section to the development docs.
Moves the reboot section from intro to dev.

[Javier Collado (javier.collado)]

When building the html files, I get some errors because trailing question marks added:

/utah-dev_doc-updates/docs/source/introduction.rst:5: WARNING: Title underline too short.

What is it?
----------
/utah-dev_doc-updates/docs/source/introduction.rst:51: WARNING: Title underline too short.

How does it work?
----------------
/utah-dev_doc-updates/docs/source/introduction.rst:51: WARNING: Title underline too short.

How does it work?
----------------

review: Needs Fixing

[Javier Collado (javier.collado)]

Aside from the comment above, I think the `FAQ` section should
be on its own instead of below `How do I start developing for it?`,
but I guess is a matter of taste.

[Joe Talbott (joetalbott)]

> Aside from the comment above, I think the `FAQ` section should
> be on its own instead of below `How do I start developing for it?`,
> but I guess is a matter of taste.

The reason I put it at that level was to avoid having all the FAQ entries show up on the index page. If you know a way around that then I'm happy to have the FAQ be one level higher.

[Javier Collado (javier.collado)]

Looking at the toctree documentation:
http://sphinx.pocoo.org/concepts.html#dir-toctree

I don't see any way to exclude from the index the children of a specific section.

[lp:~joetalbott/utah/utah-dev_doc-updates]

723. By Joe Talbott on 2012-10-25

Break FAQ section into pieces and raise its TOC level.

* Add a couple of server/provisioning FAQs while I'm here.

724. By Joe Talbott on 2012-10-25

Fix build warnings from adding '?'s to questions.

[Joe Talbott (joetalbott)]

These commits break the FAQ section into pieces which puts it at the top level and fix the errors you were seeing.

review: Needs Resubmitting

[Javier Collado (javier.collado)]

Since you're today on vacation and the documentation should be up-to-date in UDS,
I've merged the changes and made a small set of changes:

- FAQ section moved to its own file (faq.rst)
- Fixed typo (make is possible -> make it possible)
- Reformatted paragraphs with long lines to fixed width
- Changed some single quotes that were still there (from other commits) to
  double back quotes.

review: Approve

=== modified file 'docs/source/development.rst'
--- docs/source/development.rst	2012-10-19 16:44:08 +0000
+++ docs/source/development.rst	2012-10-25 19:16:20 +0000
@@ -182,6 +182,19 @@
 **In terms of settings precedence:**
 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.
 
+Running tests that need to reboot
+---------------------------------
+
+In a situation where a reboot is required.  This is handled in UTAH by marking a testcase (in the ``tc_control`` file) with::
+
+    reboot: <always, pass, never>
+
+This will make the **utah client** reboot the system under test at the **end** of the testcase after any  ``tc_cleanup`` command has finished.  Any thing that needs to be tested after the reboot should be in the testcase immediately following the testcase marked for reboot.
+
+The possible choices are ``always``, ``pass``, and ``never``.  ``never`` is the default and simply means the system under test will not reboot.  ``pass`` means the reboot will only happen if the testcase passes.  ``always``, means just that, the reboot will happen even if the test fails.
+
+Some things to keep in mind.  The **utah-client** resumes by replacing ``/etc/rc.local`` with a file that will resume the current run and will resume with the testcase following the one that triggered the reboot.  Also note that in order to have both pre- and post-reboot logging the ``-o`` flag should be used so that post-reboot output will be appended to the pre-reboot output.
+
 How to use custom preseeds
 --------------------------
 
@@ -236,6 +249,70 @@
 used in the future as well to catch some of the errors/warnings that might not
 be detected by flake8_.
 
+Frequently Asked Questions
+==========================
+
+UTAH Client FAQ
+---------------
+
+How do I install the client?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    sudo apt-add-repository ppa:utah/stable
+    sudo apt-get update
+    sudo apt-get install utah-client
+
+Is there an example testsuite I can look at?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is an `example testsuite`_.
+
+How do I run the utah-client locally?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    sudo utah -r <master.run>
+
+Why are there so many control files?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The goal of UTAH is to make sharing and reusing testsuites and
+testcases as easy as possible.  The control files make is possible to
+define testcases and testsuites fully and allow a third party using a
+testsuite or testcase the control they need to run the them in their
+own environment and to suit their own needs.
+
+Can I run the utah client on a local testsuite?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can, but it must be in a supported (``bzr``, ``git``) local repository.
+
+Why doesn't the utah client support running a testsuite in the current directory or a local copy?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to maintain tracability utah needs to know which version of a testsuite was run.  This is the reason we require testsuites be in a VCS.  This makes troubleshooting test failures and reproducing test runs in other environments much easier and more reliable.
+
+How do I get help with writing or migrating my tests to UTAH?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Send an email to [e-mail] and we will be happy to help you.
+
+UTAH Server FAQ
+---------------
+
+What provisioning methods are currently supported?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Virtual machines via ``kvm`` and ``qemu`` are currently supported and physical machines via ``cobbler``.  The physical machine support is specific to the Ubuntu Engineering QA Lab setup.
+
+Do you support provisioning LXC, existing VMS, of other methods?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Not at this time.  There are plans for adding new provisioning methods and we'd be happy to review merge proposals.  The branch is in launchpad under the UTAH_ project.
+
 .. _Guido van Rossum: https://en.wikipedia.org/wiki/Guido_van_Rossum
 .. _Barry Warsaw: http://barry.warsaw.us/
 .. _static code analysis: https://en.wikipedia.org/wiki/Static_program_analysis
@@ -246,3 +323,5 @@
 .. _Google Python Style Guide:
    http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
 .. _pylint: http://pypi.python.org/pypi/pylint/
+.. _example testsuite: https://code.launchpad.net/~utah/utah/utah_ls_example
+.. _UTAH: https://code.launchpad.net/~utah/utah/dev

=== modified file 'docs/source/introduction.rst'
--- docs/source/introduction.rst	2012-10-19 19:29:42 +0000
+++ docs/source/introduction.rst	2012-10-25 19:16:20 +0000
@@ -1,8 +1,8 @@
 Introduction
 ============
 
-What is it
-----------
+What is it?
+-----------
 
 The `Ubuntu Test Automation Harness`_ introduces new way of creating
 *end-to-end* automated test cases without having to worry about the
@@ -47,8 +47,8 @@
 test cases, the developer will just need to put the right make files and
 control files in the right places for this to happen smoothly.
 
-How does it work
-----------------
+How does it work?
+-----------------
 
 UTAH is very simple in terms of testing reliably and being able to reproduce a
 test run in a consistent manner. A command line specifies the test
@@ -73,8 +73,8 @@
 The harness allows users to build test cases and run them, some control files
 are required so that the harness knows how to deal with the code.
 
-How to start running tests
-----------------------------
+How to start running tests?
+---------------------------
 
 There are some dependencies that need to be met in order to test with VMs, in a
 nutshell::
@@ -135,17 +135,10 @@
        /usr/share/utah/client/examples/master.run \
        'http://people.canonical.com/~max/max_test.run'
 
-Running tests that need to reboot
-=================================
-
-In a situation where a reboot is required.  This is handled in UTAH by marking a testcase (in the ``tc_control`` file) with::
-
-    reboot: <always, pass, never>
-
-This will make the **utah client** reboot the system under test at the **end** of the testcase after any  ``tc_cleanup`` command has finished.  Any thing that needs to be tested after the reboot should be in the testcase immediately following the testcase marked for reboot.
-
-The possible choices are ``always``, ``pass``, and ``never``.  ``never`` is the default and simply means the system under test will not reboot.  ``pass`` means the reboot will only happen if the testcase passes.  ``always``, means just that, the reboot will happen even if the test fails.
-
-Some things to keep in mind.  The **utah-client** resumes by replacing ``/etc/rc.local`` with a file that will resume the current run and will resume with the testcase following the one that triggered the reboot.  Also note that in order to have both pre- and post-reboot logging the ``-o`` flag should be used so that post-reboot output will be appended to the pre-reboot output.
+How to start writing tests?
+---------------------------
+
+See the development_ documentation for guidance on writing and adapting tests to run under UTAH.
 
 .. _Ubuntu Test Automation Harness: https://launchpad.net/utah
+.. _development: development.html