Merge lp:~nskaggs/autopilot/apdocs-install into lp:autopilot

[Nicholas Skaggs]

Make installation it's own section, tweak the faq accordingly

Make installation it's own section, tweak the faq accordingly

[lp:~nskaggs/autopilot/apdocs-install]

527. By Nicholas Skaggs on 2015-01-21

new guide

528. By Nicholas Skaggs on 2015-01-21

add installation to toc

529. By Nicholas Skaggs on 2015-01-21

tweak

530. By Nicholas Skaggs on 2015-01-21

rebase to restruct

531. By Nicholas Skaggs on 2015-01-21

tweaks to porting links

532. By Nicholas Skaggs on 2015-01-21

fix whitespace changes

[Thomi Richards (thomir)]

LGTM

review: Approve

[lp:~nskaggs/autopilot/apdocs-install]

533. By Nicholas Skaggs on 2015-01-21

add ref for installing

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:533
http://jenkins.qa.ubuntu.com/job/autopilot-ci/989/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-vivid-amd64-ci/52
        deb: http://jenkins.qa.ubuntu.com/job/autopilot-vivid-amd64-ci/52/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-vivid-armhf-ci/52
        deb: http://jenkins.qa.ubuntu.com/job/autopilot-vivid-armhf-ci/52/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-vivid-i386-ci/52
        deb: http://jenkins.qa.ubuntu.com/job/autopilot-vivid-i386-ci/52/artifact/work/output/*zip*/output.zip
    UNSTABLE: http://jenkins.qa.ubuntu.com/job/generic-deb-autopilot-vivid-touch/917
    SUCCESS: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-vivid-autopilot/68
    UNSTABLE: http://jenkins.qa.ubuntu.com/job/generic-deb-autopilot-runner-vivid-mako/808
    SUCCESS: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-vivid-armhf/915
        deb: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-vivid-armhf/915/artifact/work/output/*zip*/output.zip
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/touch-flash-device/17315
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-testrunner-otto-vivid-autopilot/73
    SUCCESS: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-vivid-amd64/493
        deb: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-vivid-amd64/493/artifact/work/output/*zip*/output.zip

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/autopilot-ci/989/rebuild

review: Approve (continuous-integration)

[lp:~nskaggs/autopilot/apdocs-install]

534. By Nicholas Skaggs on 2015-01-22

rebase to restruct / trunk

535. By Nicholas Skaggs on 2015-01-22

fix index and refs

536. By Nicholas Skaggs on 2015-01-22

grammar

[Allan LeSage (allanlesage)]

One teensy comment, else looks fine.

review: Approve

[lp:~nskaggs/autopilot/apdocs-install]

537. By Nicholas Skaggs on 2015-01-22

fix grammar

=== modified file 'docs/_templates/indexcontent.html'
--- docs/_templates/indexcontent.html	2015-01-22 17:18:14 +0000
+++ docs/_templates/indexcontent.html	2015-01-22 17:18:15 +0000
@@ -13,6 +13,20 @@
       </td>
       <td width="50%">
         <p class="biglink">
+            <a class="biglink" href="{{ pathto("faq/troubleshooting") }}">How To Troubleshoot My Failing Test</a><br/>
+            <span class="linkdescr">My test works . . . sometimes  . . . </span>
+          </p>
+      </td>
+    </tr>
+    <tr>
+      <td width="50%">
+        <p class="biglink">
+            <a class="biglink" href="{{ pathto("guides/installation") }}">Installing Autopilot</a><br/>
+            <span class="linkdescr">I need this on my machine!</span>
+          </p>
+      </td>
+      <td width="50%">
+        <p class="biglink">
             <a class="biglink" href="{{ pathto("faq/faq") }}">Frequently Asked Questions</a><br/>
             <span class="linkdescr">... with answers!</span>
         </p>
@@ -23,7 +37,7 @@
         <p class="biglink">
             <a class="biglink" href="{{ pathto("tutorial/tutorial") }}">Autopilot Tutorial</a><br/>
             <span class="linkdescr">Grok Autopilot!</span>
-        </p>
+          </p>
       </td>
       <td width="50%">
         <p class="biglink">
@@ -37,9 +51,9 @@
         <p class="biglink">
             <a class="biglink" href="{{ pathto("guides/running_ap") }}">Running Tests</a><br/>
             <span class="linkdescr">How do I start this thing?</span>
-          </p>
+        </p>
       </td>
-     <td width="50%">
+       <td width="50%">
         <p class="biglink">
             <a class="biglink" href="{{ pathto("api/index") }}">API Reference</a><br/>
             <span class="linkdescr">API reference documentation for Autopilot.</span>
@@ -53,21 +67,13 @@
             <span class="linkdescr">Tips to bring out the test writer in you.</span>
         </p>
       </td>
-      <td width="50%">
+        <td width="50%">
         <p class="biglink">
             <a class="biglink" href="{{ pathto("appendix/appendix") }}">Appendices</a><br/>
             <span class="linkdescr">Technical documentation that doesn't fit anywhere else.</span>
         </p>
       </td>
     </tr>
-    <tr>
-      <td width="50%">
-        <p class="biglink">
-            <a class="biglink" href="{{ pathto("faq/troubleshooting") }}">How To Troubleshoot My Failing Test</a><br/>
-            <span class="linkdescr">My test works . . . sometimes  . . . </span>
-          </p>
-      </td>
-    </tr>
   </table>
 
   <h2>Indices and tables:</h2>

=== modified file 'docs/contents.rst'
--- docs/contents.rst	2015-01-22 17:18:14 +0000
+++ docs/contents.rst	2015-01-22 17:18:15 +0000
@@ -10,6 +10,7 @@
     tutorial/tutorial
     guides/good_tests
     guides/running_ap
+    guides/installation
     api/index
     porting/porting
     guides/page_object

=== modified file 'docs/faq/faq.rst'
--- docs/faq/faq.rst	2013-12-09 00:55:42 +0000
+++ docs/faq/faq.rst	2015-01-22 17:18:15 +0000
@@ -13,26 +13,21 @@
 
 The developers hang out in the #ubuntu-autopilot IRC channel on irc.freenode.net.
 
-Q. How do I install Autopilot?
-==============================
-
-Autopilot is in continuous development, and the best way to get the latest version of autopilot is to be running the latest Ubuntu development image. The autopilot developers traditionally support the Ubuntu release immediately prior to the development release via the autopilot PPA.
-
-**I am running the latest development image!**
-
-In that case you can install autopilot directly - either by installing the ``autopilot-desktop`` or ``autopilot-touch`` packages, depending on whether you are installing to a desktop or an Ubuntu Touch device.
-
-**I am running the Ubuntu release previous to the development release!**
-
-You may find that there are packages available for your Ubuntu release in the autopilot PPA. To add the PPA to your system, run the following command::
-
-    sudo add-apt-repository ppa:autopilot/ppa && sudo apt-get update
-
-Once the PPA has been added to your system, you should be able to install the same autopilot packages as if you were running the latest development release (see above).
-
-**I am running some other Linux system!**
-
-You may have to download the source code, and either run from source, or build the packages locally. Your best bet is to ask in the autopilot IRC channel ( :ref:`help_and_support`).
+Q. Which version of autopilot should I install?
+===============================================
+
+Ideally you should adopt and utilize the latest version of autopilot. If your testcase requires you to utilize an
+older version of autopilot for reasons other than :ref:`porting`, please `file a bug <https://bugs.launchpad.net/autopilot/+filebug>`_ and let the development team know about your issue.
+
+Q. Should I write my tests in python2 or python3?
+=================================================
+
+As Autopilot fully supports python3 (see :ref:`python3_support`), you should seek to use python3 for new tests. Before making a decision, you should also ensure any 3rd party modules your test may depend on also support python3.
+
+Q: Should I convert my existing tests to python3?
+=================================================
+
+See above. In a word, yes. Converting python2 to python3 (see :ref:`python3_support`) is generally straightforward and converting a testcase is likely much easier than a full python application. You can also consider retaining python2 compatibility upon conversion.
 
 Q. Where can I report a bug?
 ============================

=== added file 'docs/guides/installation.rst'
--- docs/guides/installation.rst	1970-01-01 00:00:00 +0000
+++ docs/guides/installation.rst	2015-01-22 17:18:15 +0000
@@ -0,0 +1,42 @@
+.. _installing_autopilot:
+
+Installing Autopilot
+####################
+
+.. contents::
+
+
+Autopilot is in continuous development, and the best way to get the latest version of autopilot is to run the latest Ubuntu development image. The autopilot developers traditionally support the Ubuntu release immediately prior to the development release via the autopilot PPA.
+
+Ubuntu
+======
+**I am running the latest development image!**
+
+In that case you can install autopilot directly from the repository and know you are getting the latest release. Check out the packages below.
+
+**I am running a stable version of Ubuntu!**
+
+You may install the version of autopilot in the archive directly, however it will not be up to date. Instead, you should add the latest autopilot ppa to your system (as of this writing, that is autopilot 1.5).
+
+To add the PPA to your system, run the following command::
+
+    sudo add-apt-repository ppa:autopilot/1.5 && sudo apt-get update
+
+Once the PPA has been added to your system, you should be able to install the autopilot packages below.
+
+**Which packages should I install?**
+
+Are you working on ubuntu touch applications? The ``autopilot-touch`` metapackage is for you::
+
+    sudo apt-get install autopilot-touch
+
+If you are sticking with gtk desktop applications, install the ``autopilot-desktop`` metapackage instead::
+
+    sudo apt-get install autopilot-desktop
+
+Feel free to install both metapackages to ensure you have support for all autopilot tests.
+
+Other Linux's
+=============
+
+You may have to download the source code, and either run from source, or build the packages locally. Your best bet is to ask in the autopilot IRC channel ( :ref:`help_and_support`).

=== modified file 'docs/index.rst'
--- docs/index.rst	2015-01-22 17:18:14 +0000
+++ docs/index.rst	2015-01-22 17:18:15 +0000
@@ -6,6 +6,7 @@
     tutorial/tutorial
     guides/good_tests
     guides/running_ap
+    guides/installation
     api/index
     faq/faq
     porting/porting

=== modified file 'docs/porting/porting.rst'
--- docs/porting/porting.rst	2014-04-15 02:32:16 +0000
+++ docs/porting/porting.rst	2015-01-22 17:18:15 +0000
@@ -1,3 +1,5 @@
+.. _porting:
+
 Porting Autopilot Tests
 #######################
 
@@ -74,6 +76,7 @@
 
     all_keys = app_proxy.select_many(KeyCustomProxy)
 
+.. _python3_support:
 
 Python 3
 ++++++++