User guide

The review improves User Guide, it adds steps which
describe how to clone and install os_tempest. The
new doc also mentions what has to be set in a playbook
which runs os_tempest.

Change-Id: I7e7f4bf023680904e1c5cdf67dc0113a6f30d779

doc/source/user/configuration.rst

@@ -3,7 +3,7 @@ os_tempest configuration
 ========================
 
 This page shows all of the variables which can be set in order to control
-the behaviour of `os_tempest` role and provides examples on how to do so.
+the behaviour of ``os_tempest`` role and provides examples on how to do so.
 
 For a list of all variables with a default value set, please, refer to
 the `this page`_.
@@ -11,31 +11,51 @@ the `this page`_.
 .. _this page: ./default.html
 
 
+Set the name of the cloud
+-------------------------
+
+``os-tempest`` uses named cloud credentials so it requires the name of the
+cloud the role will be executed against. The name is provided to
+``os-tempest`` via the ``tempest_cloud_name`` variable.
+In order to use named clouds a ``clouds.yaml`` file needs to be present on the
+**target host**. ``clouds.yaml`` file needs to be stored at one of the
+supported locations,
+`see here <https://docs.openstack.org/os-client-config/latest/user/configuration.html#config-files>`_
+For more information about named clouds, please, follow to the
+`os-client-config official documentation <https://docs.openstack.org/os-client-config/latest/user/index.html>`_
+
+.. warning::
+
+    ``clouds.yaml`` file has to be present on the target host - the host
+    ``os_tempest`` is gonna be executed against.
+
+
 python-tempestconf
 ------------------
-python-tempestconf is a tool which generates a `tempest.conf` file necessary
+
+python-tempestconf is a tool which generates a ``tempest.conf`` file necessary
 for Tempest execution. For more information about the tool, please,
 `follow its official documentation <https://docs.openstack.org/python-tempestconf/latest/index.html>`_.
 
-If you want `os_tempest` to execute `python-tempestconf`, prior to Tempest
+If you want ``os_tempest`` to execute ``python-tempestconf``, prior to Tempest
-execution in order to generate `tempest.conf` file, set
+execution in order to generate ``tempest.conf`` file, set
 *tempest_use_tempestconf* variable to true:
 
 .. code-block:: yaml
 
     tempest_use_tempestconf: true
 
-More information about `python-tempestconf` arguments can
+More information about ``python-tempestconf`` arguments can
 `be found here <https://docs.openstack.org/python-tempestconf/latest/cli/cli_options.html>`_.
 
-The best way how to pass any arguments to `python-tempestconf` is using its
+The best way how to pass any arguments to ``python-tempestconf`` is using its
 `profile feature <https://docs.openstack.org/python-tempestconf/latest/user/profile.html>`_.
 
-`os_tempest` provides *tempest_tempestconf_profile* variable for setting
+``os_tempest`` provides *tempest_tempestconf_profile* variable for setting
-desired `python-tempestconf` arguments.
+desired python-tempestconf's arguments.
 For example, if you wanted to define **debug** to *true*, **os-cloud** to
-*demo* and override output of `python-tempestconf` to
+*demo* and override output of ``python-tempestconf`` to
-`/my/location/tempest.conf`, it would be done by:
+``/my/location/tempest.conf``, it would be done by:
 
 .. code-block:: yaml
 

doc/source/user/index.rst

@@ -5,6 +5,7 @@ User Guide
   :maxdepth: 2
   :includehidden:
 
+  installation
   usage
   default
   configuration

doc/source/user/installation.rst

@@ -0,0 +1,33 @@
+============
+Installation
+============
+
+This page describes how to install ``os_tempest`` role.
+
+To clone or view the source code of ``os_tempest``, visit the role repository
+for `os_tempest <https://git.openstack.org/cgit/openstack/openstack-ansible-os_tempest>`_.
+
+Install dependencies via ``ansible-galaxy``:
+
+.. code-block:: shell
+
+    $ mkdir ~/.ansible/roles -p
+    $ git clone https://git.openstack.org/openstack/openstack-ansible-os_tempest ~/.ansible/roles/os_tempest
+    $ ansible-galaxy install -r ~/.ansible/roles/os_tempest/requirements.yml --roles-path=~/.ansible/roles/
+
+Then you need to export a couple of variables, `ANSIBLE_ROLES_PATH` which
+points to the directory where ``os_tempest`` was cloned and
+`ANSIBLE_ACTION_PLUGINS` which points to the location of ``config_template``
+plugin. In this case it's:
+
+.. code-block:: shell
+
+    $ export ANSIBLE_ROLES_PATH=$HOME/.ansible/roles
+    $ export ANSIBLE_ACTION_PLUGINS=~/.ansible/roles/config_template/action
+
+Then create a ``playbook.yaml``, you can find an `example one here`_.
+Then don't forget to set the name of the cloud you're going to run the role
+against, `see this page`_.
+
+.. _example one here: ./usage.html#example-playbook
+.. _see this page: ./configuration.html#set-the-name-of-the-cloud

doc/source/user/usage.rst

@@ -2,24 +2,46 @@
 Usage
 =====
 
-Basic role example
-------------------
 
-.. code-block:: yaml
+Execute by ansible-playbook
+---------------------------
 
-    - role: "os_tempest"
+First you need to install ``os_tempest`` role. For more information about the
-      ROLE_VARS...
+installation process refer to the `Installation`_ page.
 
-To clone or view the source code for this repository, visit the role repository
+.. _Installation: ./installation.html
-for `os_tempest <https://github.com/openstack/openstack-ansible-os_tempest>`_.
 
-Dependencies
+After the role is installed enter the `openstack-ansible-os_tempest` directory.
-------------
+
+First thing which needs to be done in order to execute ``os_tempest`` role
+is setting a cloud name. For information on how to do that, please, have a look
+at `Set the name of the cloud`_ page.
+
+.. _Set the name of the cloud: ../configuration.html#set-the-name-of-the-cloud
+
+An example ``playbook.yml`` can be seen below in `Example playbook`_ section.
+
+.. _Example playbook: ./usage.html#example-playbook
+
+After the required variables in the ``playbook.yml`` file are set you can
+execute the role as follows:
+
+.. code-block:: shell
+
+    $ ansible-playbook playbook.yaml
 
-This role needs pip >= 7.1 installed on the target host.
 
 Example playbook
 ----------------
 
 .. literalinclude:: ../../../examples/playbook.yml
    :language: yaml
+
+
+Dependencies
+------------
+
+This role requires the following packages to be installed on the target host:
+
+- pip >= 7.1
+- python-virtualenv

examples/playbook.yml

@@ -1,6 +1,8 @@
 ---
-- name: os_tempest role
+- hosts: localhost
-  hosts: "hosts"
+  become: true
-  user: root
+  vars:
+    tempest_cloud_name: mycloud
+    tempest_run: true
   roles:
-    - { role: "os_tempest" }
+    - os_tempest