From 0bd15f65859f2feafe8fecadb6c7a88700bfe730 Mon Sep 17 00:00:00 2001
From: Martin Kopec <mkopec@redhat.com>
Date: Mon, 25 Feb 2019 17:16:35 +0100
Subject: [PATCH] Document os_tempest configuration options

The review adds documentation of configuration options regarding
python-tempestconf.
The change is part of adding user documentation process, see
https://tree.taiga.io/project/tripleo-ci-board/task/583

Change-Id: Iee91ed5bcf5cf5db3df42e9cd40178b10f1c38f8
---
 doc/source/user/configuration.rst | 45 +++++++++++++++++++++++++++++++
 doc/source/user/index.rst         |  1 +
 2 files changed, 46 insertions(+)
 create mode 100644 doc/source/user/configuration.rst

diff --git a/doc/source/user/configuration.rst b/doc/source/user/configuration.rst
new file mode 100644
index 00000000..0cca0b30
--- /dev/null
+++ b/doc/source/user/configuration.rst
@@ -0,0 +1,45 @@
+========================
+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.
+
+For a list of all variables with a default value set, please, refer to
+the `this page`_.
+
+.. _this page: ./default.html
+
+
+python-tempestconf
+------------------
+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
+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
+`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
+`profile feature <https://docs.openstack.org/python-tempestconf/latest/user/profile.html>`_.
+
+`os_tempest` provides *tempest_tempestconf_profile* variable for setting
+desired `python-tempestconf` arguments.
+For example, if you wanted to define **debug** to *true*, **os-cloud** to
+*demo* and override output of `python-tempestconf` to
+`/my/location/tempest.conf`, it would be done by:
+
+.. code-block:: yaml
+
+    tempest_tempestconf_profile:
+      debug: true
+      os-cloud: demo
+      out: /my/location/tempest.conf
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
index cbfcde72..b1fa11a7 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -7,3 +7,4 @@ User Guide
 
   usage
   default
+  configuration