Update documentation and add a job to publish it

A few info was outdated or duplicated, this patch resolves those
inconsistencies.
The patch also adds a job that builds and publishes the plugin
documentation.

Change-Id: Ibe334eee5a39f773d0fbdb5c95fc5ae3e3bb4409

.zuul.yaml

@@ -3,6 +3,8 @@
     templates:
       - check-requirements
       - tempest-plugin-jobs
+      - publish-openstack-docs-pti
+      - release-notes-jobs-python3
     check:
       jobs:
         - watcherclient-tempest-functional

CONTRIBUTING.rst

@@ -1,17 +1,17 @@
 If you would like to contribute to the development of OpenStack, you must
-follow the steps in this page:
+follow the steps on this page:
 
-   https://docs.openstack.org/infra/manual/developers.html
+   https://docs.opendev.org/opendev/infra-manual/latest/developers.html
 
 If you already have a good understanding of how the system works and your
 OpenStack accounts are set up, you can skip to the development workflow
 section of this documentation to learn how changes to OpenStack should be
 submitted for review via the Gerrit tool:
 
-   https://docs.openstack.org/infra/manual/developers.html#development-workflow
+   https://docs.opendev.org/opendev/infra-manual/latest/developers.html#development-workflow
 
 Pull requests submitted through GitHub will be ignored.
 
 Bugs should be filed on Launchpad, not GitHub:
 
-   https://bugs.launchpad.net/Tempest plugin watcher-tempest-plugin
+   https://bugs.launchpad.net/watcher-tempest-plugin

README.rst

@@ -2,19 +2,18 @@
 watcher-tempest-plugin
 ======================
 
-Description
+This repository contains a `Tempest`_ `test plugin`_ to verify the
+functionality of the `Watcher`_ service.
 
-Please fill here a long description which must be at least 3 lines wrapped on
+See the following docs to learn more:
-80 cols, so that distribution package maintainers can use it in their packages.
-Note that this is a hard requirement.
 
 * Free software: Apache license
-* Documentation: https://docs.openstack.org/watcher/latest/ plugin watcher-tempest-plugin
+* Documentation: https://docs.openstack.org/watcher-tempest-plugin/latest/
-* Release notes: https://docs.openstack.org/releasenotes/watcher/ plugin watcher-tempest-plugin
+* Release notes: https://docs.openstack.org/releasenotes/watcher-tempest-plugin/
 * Source: https://opendev.org/openstack/watcher-tempest-plugin
 * Bugs: https://bugs.launchpad.net/watcher plugin watcher-tempest-plugin
 
-Features
+.. _Tempest: https://docs.openstack.org/tempest
---------
+.. _test plugin: https://docs.openstack.org/tempest/latest/plugin.html
+.. _Watcher: https://docs.openstack.org/watcher/latest/
 
-* TODO

doc/source/readme.rst

@@ -20,14 +20,15 @@ Tempest installation
 
 To install Tempest you can issue the following commands::
 
-    $ git clone https://github.com/openstack/tempest/
+    $ git clone https://opendev.org/openstack/tempest
     $ cd tempest/
     $ pip install .
 
-The folder you are into now will be called ``<TEMPEST_DIR>`` from now onwards.
+The folder's path you are now in will be called ``<TEMPEST_DIR>`` from now
+onwards.
 
-Please note that although it is fully working outside a virtual environment, it
+Please note that although it is fully working outside a `virtual environment`_,
-is recommended to install within a `venv`.
+it is recommended to install within a `venv`.
 
 
 Watcher Tempest testing setup
@@ -38,7 +39,7 @@ following command::
 
     $  pip install -e <WATCHER_SRC_DIR>
 
-Then setup a local working environment (here ``watcher-cloud``) for running
+Then set up a local working environment (here ``watcher-cloud``) for running
 Tempest for Watcher which shall contain the configuration for your OpenStack
 integration platform.
 
@@ -58,7 +59,7 @@ issue the following commands::
     $ cd <TEMPEST_DIR>/watcher-cloud/etc
     $ cp tempest.conf.sample tempest.conf
 
-At this point you need to edit the ``watcher-cloud/etc/tempest.conf``
+At this point, you need to edit the ``watcher-cloud/etc/tempest.conf``
 file as described in the `Tempest configuration guide`_.
 Shown below is a minimal configuration you need to set within your
 ``tempest.conf`` configuration file which can get you started.
@@ -85,8 +86,8 @@ You now have the minimum configuration for running Watcher Tempest tests on a
 single node.
 
 Since deploying Watcher with only a single compute node is not very useful, a
-few more configuration have to be set in your ``tempest.conf`` file in order to
+few more configurations have to be set in your ``tempest.conf`` file in order
-enable the execution of multi-node scenarios::
+to enable the execution of multi-node scenarios::
 
     [compute]
     # To indicate Tempest test that you have provided enough compute nodes
@@ -117,13 +118,13 @@ To run only these tests in Tempest, you can then issue these commands::
 
     $ tempest run --config-file watcher-cloud/etc/tempest.conf --regex watcher_tempest_plugin
 
-Or alternatively the following commands if you are::
+Alternatively, the following commands if you are in the Tempest directory::
 
     $ cd <TEMPEST_DIR>/watcher-cloud
     $ tempest run --regex watcher_tempest_plugin
 
-To run a single test case, go to Tempest directory, then run with test case
+To run a single test case, go to the Tempest directory, then run with the test
-name, e.g.::
+case name, e.g.::
 
     $ cd <TEMPEST_DIR>
     $ tempest run --config-file watcher-cloud/etc/tempest.conf --regex \
@@ -136,9 +137,20 @@ before you can do so, you need to follow the Tempest explanation on running
     $ export TEMPEST_CONFIG_DIR=<TEMPEST_DIR>/watcher-cloud/etc/
     $ tox -eall-plugin watcher
 
-.. _tox with plugins: https://docs.openstack.org/tempest/latest/plugin.html#notes-for-using-plugins-with-virtualenvs
+.. _tox with plugins: https://docs.openstack.org/tempest/latest/plugins/plugin.html#notes-for-using-plugins-with-virtualenvs
 
 And, to run a specific test::
 
     $ export TEMPEST_CONFIG_DIR=<TEMPEST_DIR>/watcher-cloud/etc/
     $ tox -eall-plugin watcher_tempest_plugin.tests.api.admin.test_audit_template.TestCreateDeleteAuditTemplate.test_create_audit_template
+
+Watcherclient Tempest tests execution
+-------------------------------------
+
+To run Watcherclient functional tests you need to execute ``tempest run`` command::
+
+    $ tempest run --regex watcher_tempest_plugin.tests.client_functional
+
+You can run specified test(s) by using a regular expression::
+
+    $ tempest run --regex watcher_tempest_plugin.tests.client_functional.v1.test_action.ActionTests.test_action_list

watcher_tempest_plugin/README.rst

@@ -1,170 +0,0 @@
-..
-      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/
-
-.. _tempest_tests:
-
-Tempest tests
-=============
-
-The following procedure gets you started with Tempest testing but you can also
-refer to the `Tempest documentation`_ for more details.
-
-.. _Tempest documentation: https://docs.openstack.org/tempest/latest
-
-
-Tempest installation
---------------------
-
-To install Tempest you can issue the following commands::
-
-    $ git clone https://github.com/openstack/tempest/
-    $ cd tempest/
-    $ pip install .
-
-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`.
-
-
-Watcher Tempest testing setup
------------------------------
-
-You can now install Watcher alongside it in development mode by issuing the
-following command::
-
-    $  pip install -e <WATCHER_SRC_DIR>
-
-Then setup a local working environment (here ``watcher-cloud``) for running
-Tempest for Watcher which shall contain the configuration for your OpenStack
-integration platform.
-
-In a virtual environment, you can do so by issuing the following command::
-
-    $ cd <TEMPEST_DIR>
-    $ tempest init watcher-cloud
-
-Otherwise, if you are not using a virtualenv::
-
-    $ cd <TEMPEST_DIR>
-    $ tempest init --config-dir ./etc watcher-cloud
-
-By default the configuration file is empty so before starting, you need to
-issue the following commands::
-
-    $ cd <TEMPEST_DIR>/watcher-cloud/etc
-    $ cp tempest.conf.sample tempest.conf
-
-At this point you need to edit the ``watcher-cloud/etc/tempest.conf``
-file as described in the `Tempest configuration guide`_.
-Shown below is a minimal configuration you need to set within your
-``tempest.conf`` configuration file which can get you started.
-
-For Keystone V3::
-
-    [identity]
-    uri_v3 = http://<KEYSTONE_PUBLIC_ENDPOINT_IP>:<KEYSTONE_PORT>/v3
-    auth_version = v3
-
-    [auth]
-    admin_username = <ADMIN_USERNAME>
-    admin_password = <ADMIN_PASSWORD>
-    admin_tenant_name = <ADMIN_TENANT_NAME>
-    admin_domain_name = <ADMIN_DOMAIN_NAME>
-
-    [identity-feature-enabled]
-    api_v2 = false
-    api_v3 = true
-
-For Keystone V2::
-
-    [identity]
-    uri = http://<KEYSTONE_PUBLIC_ENDPOINT_IP>:<KEYSTONE_PORT>/v2.0
-    auth_version = v2
-
-    [auth]
-    admin_tenant_name = <ADMIN_TENANT_NAME>
-    admin_username = <ADMIN_USERNAME>
-    admin_password = <ADMIN_PASSWORD>
-
-In both cases::
-
-    [network]
-    public_network_id = <PUBLIC_NETWORK_ID>
-
-You now have the minimum configuration for running Watcher Tempest tests on a
-single node.
-
-Since deploying Watcher with only a single compute node is not very useful, a
-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 you have provided enough compute nodes
-    min_compute_nodes = 2
-
-    # Image UUID you can get using the "glance image-list" command
-    image_ref = <IMAGE_UUID>
-
-
-For more information, please refer to:
-
-- Keystone connection: https://docs.openstack.org/tempest/latest/configuration.html#keystone-connection-info
-- Dynamic Keystone Credentials: https://docs.openstack.org/tempest/latest/configuration.html#dynamic-credentials
-
-.. _virtual environment: https://docs.python-guide.org/dev/virtualenvs/
-.. _Tempest configuration guide: https://docs.openstack.org/tempest/latest/configuration.html
-
-
-Watcher Tempest tests execution
--------------------------------
-
-To list all Watcher Tempest cases, you can issue the following commands::
-
-    $ cd <TEMPEST_DIR>
-    $ testr list-tests watcher
-
-To run only these tests in Tempest, you can then issue these commands::
-
-    $ ./run_tempest.sh --config watcher-cloud/etc/tempest.conf -N -- watcher
-
-Or alternatively the following commands if you are::
-
-    $ cd <TEMPEST_DIR>/watcher-cloud
-    $ ../run_tempest.sh -N -- watcher
-
-To run a single test case, go to Tempest directory, then run with test case
-name, e.g.::
-
-    $ cd <TEMPEST_DIR>
-    $ ./run_tempest.sh --config watcher-cloud/etc/tempest.conf -N \
-        -- watcher_tempest_plugin.tests.api.admin.test_audit_template.TestCreateDeleteAuditTemplate.test_create_audit_template
-
-Alternatively, you can also run the Watcher Tempest plugin tests using tox. But
-before you can do so, you need to follow the Tempest explanation on running
-`tox with plugins`_. Then, run::
-
-    $ export TEMPEST_CONFIG_DIR=<TEMPEST_DIR>/watcher-cloud/etc/
-    $ tox -eall-plugin watcher
-
-.. _tox with plugins: https://docs.openstack.org/tempest/latest/plugin.html#notes-for-using-plugins-with-virtualenvs
-
-And, to run a specific test::
-
-    $ export TEMPEST_CONFIG_DIR=<TEMPEST_DIR>/watcher-cloud/etc/
-    $ tox -eall-plugin watcher_tempest_plugin.tests.api.admin.test_audit_template.TestCreateDeleteAuditTemplate.test_create_audit_template
-
-
-Watcherclient Tempest tests execution
--------------------------------
-
-To run Watcherclient functional tests you need to execute ``tempest run`` command::
-
-    $ tempest run --regex watcher_tempest_plugin.tests.client_functional
-
-You can run specified test(s) by using regular expression::
-
-    $ tempest run --regex watcher_tempest_plugin.tests.client_functional.v1.test_action.ActionTests.test_action_list