Improve role docs, remove unused var

* Fix typos and highlight role variables which are required for
  that roles.
* Highlight titles in Readme files.
* Remove default definition of unused variable in generate-tempestconf-file
  role.

Change-Id: If816ea50bc200ed0bfdf1233725616d4a8783d06

roles/create-clouds-yaml-file/README.rst

@@ -1,9 +1,11 @@
 Creates clouds.yaml file
+========================
 
 Source credentials and create a clouds.yaml file. If the clouds.yaml
 file in the defined location exists, it will be overwritten.
-Note: If there is a file int the location, where clouds_file_path points, called
-openstack, it will be removed and directory called openstack will be created.
+Note: If there is a file called openstack in the location, where
+clouds_file_path points, it will be removed and directory called openstack
+will be created.
 
 **Role Variables**
 
@@ -11,18 +13,30 @@ openstack, it will be removed and directory called openstack will be created.
    :type: string
    :default: /etc/openstack/clouds.yaml
 
-    A path to the clouds.yaml file.
+   A path to the clouds.yaml file.
 
 .. zuul:rolevar:: source_credentials_commands
    :type: string
    :default: None
+   :required: True
 
-    A file or command to be sourced for obtaining credentials.
+   Commands divided by a semicolon which define obtaining credentials.
+   They need to be defined in the playbook the role is called from.
+   For example for devstack it's used ({{ devstack_base_dir}} is the location
+   where run-devstack role copies devstack source files):
+
+   `source {{ devstack_base_dir }}/devstack/openrc {{ user }} {{ user }}`
+
+   and for packstack ({{ ansible_user_dir }} is the location where
+   packstack generates rc files):
+
+   `source {{ ansible_user_dir }}/keystonerc_{{ user }}`
 
 .. zuul:rolevar:: cloudname
    :type: string
    :default: None
+   :required: True
 
-    A cloudname under which will be sourced credentials saved
-    in clouds.yaml file
+   A cloudname under which sourced credentials will be saved
+   in clouds.yaml file.
 

roles/create-keystonerc-files/README.rst

@@ -1,6 +1,7 @@
 Create keystonerc files
+=======================
 
-Creates keystonerc files for tempest, print them to the output and copy them
+Create keystonerc files for tempest, print them to the output and copy them
 to the wanted destination.
 
 **Role Variables**
@@ -8,7 +9,7 @@ to the wanted destination.
 .. zuul:rolevar:: admin_user
    :type: dict
 
-    A dictionary of admin user credentials.
+   A dictionary of admin user credentials.
 
    .. zuul:rolevar:: username
       :default: admin
@@ -34,7 +35,7 @@ to the wanted destination.
 .. zuul:rolevar:: demo_user
    :type: dict
 
-    A dictionary of demo user credentials.
+   A dictionary of demo user credentials.
 
    .. zuul:rolevar:: username
       :default: demo

roles/generate-accounts-file/README.rst

@@ -1,4 +1,5 @@
-# Generate accounts.yaml file for tempest
+Generate accounts.yaml file for tempest
+=======================================
 
 Installs tempest cloned from git and generates accounts.yaml file.
 accounts.yaml file will be saved inside the cloned folder in etc/ subfolder.
@@ -14,52 +15,56 @@ which may be there.
 .. zuul:rolevar:: tempest_concurrency
    :default: 2
 
-    The number of parallel test processes.
+   A number of parallel test processes.
 
 .. zuul:rolevar:: tempest_config_file
    :type: string
    :default: None
+   :required: True
 
-    A path to a tempest configuration file. It must contain credentials
-    which allows to create resources.
+   A path to a tempest configuration file. It must contain credentials
+   which allows to create resources.
 
-.. zuul:rolevar: source_credentials_commands
+.. zuul:rolevar:: source_credentials_commands
    :type: string
    :default: None
+   :required: True
 
-   Commands divided by a semicolon which defines sourcing credentials for
+   Commands divided by a semicolon which define obtaining credentials for
    a user who has permissions to create resources. They need to be defined
    in the playbook the role is called from.
-   For example for devstack:
+   For example for devstack it's used ({{ devstack_base_dir}} is the location
+   where run-devstack role copies devstack source files):
 
-   `source ./openrc admin admin`
+   `source {{ devstack_base_dir }}/devstack/openrc {{ user }} {{ user }}`
 
-   and for packstack:
+   and for packstack ({{ ansible_user_dir }} is the location where
+   packstack generates rc files):
 
-   `source ./keystonerc_admin`
+   `source {{ ansible_user_dir }}/keystonerc_{{ user }}`
 
 .. zuul:rolevar:: virtualenvs
    :type: dict
 
-    A dictionary of paths to virtual environments.
+   A dictionary of paths to virtual environments.
 
    .. zuul:rolevar:: tempest
       :default: ~/.virtualenvs/.tempest
 
-       The path to the virtual environment of Tempest.
+      A path to the virtual environment of Tempest.
 
 .. zuul:rolevar:: tempest_src_relative_path
    :type: string
 
-    A relative path to Tempest project which is by default cloned to the
-    Zuul home directory. Value of the variable is set in the role to that
-    default path. If needed, the variable can be overridden from the
-    playbook where the role is called.
+   A relative path to Tempest project which is by default cloned to the
+   Zuul home directory. Value of the variable is set in the role to that
+   default path. If needed, the variable can be overridden from the
+   playbook where the role is called from.
 
 .. zuul:rolevar:: accounts_file_destination
    :type: string
    :default: None
 
-    If the variable is defined, the newly generated accounts.yaml file
-    will be copied to the directory specified by the variable.
+   If the variable is defined, the newly generated accounts.yaml file
+   will be copied to the directory specified by the variable.
 

roles/generate-tempestconf-file-cloud/README.rst

@@ -1,8 +1,9 @@
 Generate configuration file for tempest from cloud credentials
+==============================================================
 
 Installs python-tempestconf cloned from git and generates tempest.conf with
 credentials saved in clouds.yaml file. The tempest configuration file is printed
-to the output.
+to the output after that.
 
 **Role Variables**
 
@@ -15,23 +16,23 @@ to the output.
 .. zuul:rolevar:: virtualenvs
    :type: dict
 
-    A dictionary of paths to virtual environments.
+   A dictionary of paths to virtual environments.
 
    .. zuul:rolevar:: tempestconf
       :default: ~/.virtualenvs/.tempestconf
 
-       The path to the virtual environment of python-tempestconf tool.
+      A path to the virtual environment of python-tempestconf tool.
 
 .. zuul:rolevar:: url_cirros_image
    :type: string
    :default: http://download.cirros-cloud.net/0.3.5/cirros-0.3.5-x86_64-disk.img
 
-    A URL address of the cirros image.
+   A URL address of the cirros image.
 
 .. zuul:rolevar:: tempestconf_src_relative_path
    :type: string
 
-    A relative path to a python-tempestconf project which is by default cloned
-    to the Zuul home directory. Value of the variable is set in the role to
-    that default path. If needed, the variable can be overridden from the
-    playbook where the role is called.
+   A relative path to a python-tempestconf project which is by default cloned
+   to the Zuul home directory. Value of the variable is set in the role to
+   that default path. If needed, the variable can be overridden from the
+   playbook where the role is called from.

roles/generate-tempestconf-file-cloud/tasks/main.yaml

@@ -9,7 +9,7 @@
         - setuptools
         - pbr
 
-  - name: Debug, list tempetsconf dir
+  - name: Debug, list tempestconf dir
     shell: |
         set -ex
         ls -all .

roles/generate-tempestconf-file/README.rst

@@ -1,4 +1,5 @@
-# Generate configuration file for tempest
+Generate configuration file for tempest
+=======================================
 
 Installs python-tempestconf cloned from git and generates tempest.conf which
 is then copied to tempest directory.
@@ -9,22 +10,23 @@ is then copied to tempest directory.
    :type: string
    :default: /opt/stack
 
-    The devstack base directory.
+   The devstack base directory.
 
 .. zuul:rolevar:: virtualenvs
    :type: dict
 
-    A dictionary of paths to virtual environments.
+   A dictionary of paths to virtual environments.
 
    .. zuul:rolevar:: tempestconf
       :default: ~/.virtualenvs/.tempestconf
 
-       The path to the virtual environment of python-tempestconf tool.
+      A path to the virtual environment of python-tempestconf tool.
 
 .. zuul:rolevar:: source_credentials_commands
    :type: string
+   :required: True
 
-   Commands divided by a semicolon which defines sourcing credentials for
+   Commands divided by a semicolon which define obtaining credentials for
    running python-tempestconf tool with. They need to be defined in the
    playbook the role is called from.
    For example for devstack it's used ({{ devstack_base_dir}} is the location
@@ -32,7 +34,8 @@ is then copied to tempest directory.
 
    `source {{ devstack_base_dir }}/devstack/openrc {{ user }} {{ user }}`
 
-   and for packstack:
+   and for packstack ({{ ansible_user_dir }} is the location where
+   packstack generates rc files):
 
    `source {{ ansible_user_dir }}/keystonerc_{{ user }}`
 
@@ -40,15 +43,15 @@ is then copied to tempest directory.
    :type: string
    :default: http://download.cirros-cloud.net/0.3.5/cirros-0.3.5-x86_64-disk.img
 
-    A URL address of the cirros image.
+   A URL address of the cirros image.
 
 .. zuul:rolevar:: tempestconf_src_relative_path
    :type: string
 
-    A relative path to a python-tempestconf project which is by default cloned
-    to the Zuul home directory. Value of the variable is set in the role to
-    that default path. If needed, the variable can be overridden from the
-    playbook where the role is called.
+   A relative path to a python-tempestconf project which is by default cloned
+   to the Zuul home directory. Value of the variable is set in the role to
+   that default path. If needed, the variable can be overridden from the
+   playbook where the role is called.
 
 
 .. zuul:rolevar:: aditional_tempestconf_params
@@ -85,6 +88,7 @@ is then copied to tempest directory.
 .. zuul:rolevar:: cloud_admin
    :type: string
    :default: None
+   :required: required if test_demo_user == True
 
    Name of credentials from clouds.yaml file, which will be used to create
    tempest resources in case, test_demo_user variable is set to True.

roles/generate-tempestconf-file/defaults/main.yaml

@@ -1,6 +1,5 @@
 devstack_base_dir: /opt/stack
 virtualenvs:
-    tempest: ~/.virtualenvs/.tempest
     tempestconf: ~/.virtualenvs/.tempestconf
 url_cirros_image: "http://download.cirros-cloud.net/0.3.5/cirros-0.3.5-x86_64-disk.img"
 aditional_tempestconf_params: ""

roles/generate-tempestconf-file/tasks/main.yaml

@@ -43,7 +43,7 @@
   - include: test-demo-user.yaml
     when: test_demo_user
 
-  - name: Generate tempest configuration filea
+  - name: Generate tempest configuration file
     shell: |
         ./generate-tempestconf.sh
     args:

roles/tempestconf-workaround-auth-url/README.rst

@@ -1,4 +1,5 @@
 Workaround clouds.yaml file
+===========================
 
 Workaround for AUTH URL in clouds.yaml file.
 auth_url needs to be edited in devstack environment so that
@@ -10,5 +11,5 @@ it contains "/v3" as a suffix.
    :type: string
    :default: /etc/openstack/clouds.yaml
 
-    A path to the clouds.yaml file.
+   A path to the clouds.yaml file.