Updated Watcher doc to mention Tempest tests

The Watcher Tempest tests are only mentioned inside a README.rst.
They are now part of the main documentation.

Change-Id: Ieca85dc7f7307b45e4b99af4a4600a8c2d2b59d7
Closes-Bug: #1536993

doc/source/dev/devstack.rst

@@ -131,3 +131,13 @@ In essence, this means that every compute node's root user's public RSA key
 must exist in every other compute node's stack user's authorized_keys file and
 every compute node's public ECDSA key needs to be in every other compute
 node's root user's known_hosts file.
+
+
+Environment final checkup
+-------------------------
+
+If you are willing to make sure everything is in order in your DevStack
+environment, you can run the Watcher Tempest tests which will validate its API
+but also that you can perform the typical Watcher workflows. To do so, have a
+look at the :ref:`Tempest tests <tempest_tests>` section which will explain to
+you how to run them.

doc/source/dev/environment.rst

@@ -143,34 +143,13 @@ You should then be able to `import watcher` using Python without issue:
 
 If you can import watcher without a traceback, you should be ready to develop.
 
-Run Watcher unit tests
+Run Watcher tests
-======================
+=================
 
-All unit tests should be run using tox. To run the unit tests under py27 and
+Watcher provides both :ref:`unit tests <unit_tests>` and
-also run the pep8 tests:
+:ref:`functional/tempest tests <tempest_tests>`. Please refer to :doc:`testing`
+to understand how to run them.
 
-.. code-block:: bash
-
-    $ workon watcher
-    (watcher) $ pip install tox
-
-    (watcher) $ cd watcher
-    (watcher) $ tox -epep8 -epy27
-
-You may pass options to the test programs using positional arguments. To run a
-specific unit test, this passes the -r option and desired test (regex string)
-to os-testr:
-
-.. code-block:: bash
-
-    $ workon watcher
-    (watcher) $ tox -epy27 -- tests.api
-
-When you're done, deactivate the virtualenv:
-
-.. code-block:: bash
-
-    $ deactivate
 
 Build the Watcher documentation
 ===============================

doc/source/dev/testing.rst

@@ -0,0 +1,50 @@
+..
+      Except where otherwise noted, this document is licensed under Creative
+      Commons Attribution 3.0 License.  You can view the license at:
+
+          https://creativecommons.org/licenses/by/3.0/
+
+=======
+Testing
+=======
+
+.. _unit_tests:
+
+Unit tests
+==========
+
+All unit tests should be run using `tox`_. To run the same unit tests that are
+executing onto `Gerrit`_ which includes ``py34``, ``py27`` and ``pep8``, you
+can issue the following command::
+
+    $ workon watcher
+    (watcher) $ pip install tox
+    (watcher) $ cd watcher
+    (watcher) $ tox
+
+If you want to only run one of the aforementioned, you can then issue one of
+the following::
+
+    $ workon watcher
+    (watcher) $ tox -e py34
+    (watcher) $ tox -e py27
+    (watcher) $ tox -e pep8
+
+.. _tox: https://tox.readthedocs.org/
+.. _Gerrit: http://review.openstack.org/
+
+You may pass options to the test programs using positional arguments. To run a
+specific unit test, you can pass extra options to `os-testr`_ after putting
+the ``--`` separator. So using the ``-r`` option followed by a regex string,
+you can run the desired test::
+
+    $ workon watcher
+    (watcher) $ tox -e py27 -- -r watcher.tests.api
+
+.. _os-testr: http://docs.openstack.org/developer/os-testr/
+
+When you're done, deactivate the virtualenv::
+
+    $ deactivate
+
+.. include:: ../../../watcher_tempest_plugin/README.rst

doc/source/index.rst

@@ -53,6 +53,7 @@ Getting Started
   dev/environment
   dev/devstack
   deploy/configuration
+  dev/testing
 
 
 API References

watcher_tempest_plugin/README.rst

@@ -4,14 +4,11 @@
 
           https://creativecommons.org/licenses/by/3.0/
 
-.. _tempest_integration:
+.. _tempest_tests:
 
-=============
 Tempest tests
 =============
 
-This directory contains Tempest tests to cover Watcher project.
-
 The following procedure gets you started with Tempest testing but you can also
 refer to the `Tempest documentation`_ for more details.
 
@@ -19,7 +16,7 @@ refer to the `Tempest documentation`_ for more details.
 
 
 Tempest installation
-====================
+--------------------
 
 To install Tempest you can issue the following commands::
 
@@ -30,11 +27,11 @@ To install Tempest you can issue the following commands::
 The folder you are into now will be called ``<TEMPEST_DIR>`` from now onwards.
 
 Please note that although it is fully working outside a virtual environment, it
-is recommended to install within a venv.
+is recommended to install within a `venv`.
 
 
 Watcher Tempest testing setup
-=============================
+-----------------------------
 
 You can now install Watcher alongside it in development mode by issuing the
 following command::
@@ -43,7 +40,7 @@ following command::
 
 Then setup a local working environment (here ``watcher-cloud``) for running
 Tempest for Watcher which shall contain the configuration for your OpenStack
-intergration platform.
+integration platform.
 
 In a virtual environment, you can do so by issuing the following command::
 
@@ -106,7 +103,7 @@ few more configuration have to be set in your ``tempest.conf`` file in order to
 enable the execution of multi-node scenarios::
 
     [compute]
-    # To indicate Tempest test that yout have provided enough compute nodes
+    # To indicate Tempest test that you have provided enough compute nodes
     min_compute_nodes = 2
 
     # Image UUID you can get using the "glance image-list" command
@@ -123,7 +120,7 @@ For more information, please refer to:
 
 
 Watcher Tempest tests execution
-===============================
+-------------------------------
 
 To list all Watcher Tempest cases, you can issue the following commands::