Update documentation

This is a quick update for the test-operator documentation.
The following sections were udpated:
    - Test Images
    - User Guide
        - Running Operator Locally
        - Running Operator Using The Operator Lifecycle Manager (OLM)
        - Custom Tempest Configuration

This patch also updates the workflow document that defines the docs
job. The change ensures that the documentation jobs are executed
only when a change to the documentation was made.

.github/workflows/documentation.yaml

@@ -3,8 +3,14 @@ on:
   push:
     branches:
       - main
+    paths:
+      - docs/**
   pull_request:
+    paths:
+      - docs/**
   workflow_dispatch:
+    paths:
+      - docs/**
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:

docs/source/guide.rst

@@ -3,27 +3,113 @@ User Guide
 
 This guide is a starting point for configuring and running the `test-operator`.
 
-Installation
-------------
+
+Running Operator Locally
+------------------------
+This is **quick and easy way** how to experiment with the operator during development of a
+new feature.
 
 .. code-block:: bash
 
-    make install
+    make install run
 
-Execution
----------
-Execute the following command to run the operator. Note, that after running the
-following command you will need to switch to another terminal unless you run it
-in the background.
+Note, that after running the following command you will need to switch to
+another terminal unless you run it in the background.
 
-.. code-block:: bash
+Running Operator Using The Operator Lifecycle Manager (OLM)
+-----------------------------------------------------------
 
-    make run
+Another option is to start the operator by running the pre-build operator image
+stored on
+`quay.io <https://quay.io/repository/openstack-k8s-operators/test-operator>`_
+using the OLM.
 
 .. note::
-    You can run this step together with the installation at once by running: ``make install run``
 
-Then apply a tempest resource definition, e.g. the default one:
+   Currently, the `test-operator <https://quay.io/openstack-k8s-operators/test-operator>`_ is not
+   part of the `openstack-operator-index <https://quay.io/openstack-k8s-operators/
+   openstack-operator-index>`_ therefore a new catalog source which uses `test-operator-index
+   <https://quay.io/openstack-k8s-operators /test-operator-index>`_ image needs to be created
+   in advance.
+
+Follow these steps to install the operator in the openstack project.
+
+1. Create **OperatorGroup**
+
+.. code-block:: yaml
+
+   cat operator-group.yaml
+   ---
+   apiVersion: operators.coreos.com/v1
+   kind: OperatorGroup
+   metadata:
+     name: openstack-operatorgroup
+     namespace: openstack
+   spec:
+     targetNamespaces:
+       - openstack
+
+.. code-block:: bash
+
+   oc apply -f operator-group.yaml
+
+2. Create **CatalogSource**
+
+.. code-block:: yaml
+
+   cat catalog-source.yaml
+   ---
+   apiVersion: operators.coreos.com/v1alpha1
+   kind: CatalogSource
+   metadata:
+     name: test-operator-index
+     namespace: openstack
+   spec:
+     sourceType: grpc
+     image: quay.io/openstack-k8s-operators/test-operator-index:latest
+
+.. code-block:: bash
+
+   oc apply -f catalog-source.yaml
+
+3. Create **Subscription**
+
+.. code-block:: yaml
+
+   cat subscription.yaml
+   ---
+   apiVersion: operators.coreos.com/v1alpha1
+   kind: Subscription
+   metadata:
+     name: test-operator
+     namespace: openstack
+   spec:
+     name: test-operator
+     source: test-operator-index
+     sourceNamespace: openstack
+
+.. code-block:: bash
+
+   oc apply -f subscription.yaml
+
+4. Wait for the **test-operator-controller-manager** pod to successfully spawn. Once you see
+   the pod running you can start to communicate with the operator using the **Tempest** resource
+   defined below.
+
+.. code-block:: bash
+
+   oc get pods
+   ...
+   test-operator-controller-manager-6c9994847c-6jwn5                 2/2     Running     0              20s
+   ...
+
+
+Executing Tempest Tests
+-----------------------
+.. _Executing Tempest Tests:
+
+Once you have an operator running, then you can apply a tempest resource
+definition, e.g. the default one:
 
 .. literalinclude:: ../../config/samples/test_v1beta1_tempest.yaml
    :language: yaml
@@ -48,8 +134,43 @@ To see the console output of the execution run the following:
 
 Custom Tempest Configuration
 ----------------------------
-This is TBA.
+To configure tempest via tempest.conf use the `tempestconfRun.overrides`
+parameter. This parameter accepts a list of key value pairs that specify values
+that should be written to tempest.conf generated inside the container.
+
+For example this definition of Tempest object:
+
+.. code-block:: yaml
+
+    ---
+    apiVersion: test.openstack.org/v1beta1
+    kind: Tempest
+    metadata:
+      name: tempest-tests
+      namespace: openstack
+    spec:
+      containerImage: quay.io/podified-antelope-centos9/openstack-tempest:current-podified
+      tempestRun:
+        includeList: | # <-- Use | to preserve \n
+          tempest.api.identity.v3.*
+        concurrency: 8
+        tempestconfRun:
+          overrides: |
+            auth.admin_username admin
+            auth.admin_password 1234
+
+will ensure that tempest will be executed with tempest.conf that looks like this:
+
+
+.. code-block:: toml
+
+   ...
+   [auth]
+   admin_username = admin
+   admin_password = 1234
+   ...
+
 
-Getting logs
+Getting Logs
 ------------
 This is TBA.

docs/source/images.rst

@@ -17,8 +17,28 @@ and filter for *tempest* results.
 Currently, there are the following tempest images:
 
 * `openstack-tempest <https://quay.io/podified-antelope-centos9/openstack-tempest>`_
+
+  An image that contains only tempest and no other plugins. The user can install any external
+  plugin during the container execution using the `tempestRun.externalPlugin*` parameters
+  (see :ref:`Executing Tempest Tests<Executing Tempest Tests>`)
+
+* `openstack-tempest-all <https://quay.io/podified-antelope-centos9/openstack-tempest-all>`_
+
+  An image that contains tempest and all plugins that have an rpm:
+
+  `neutron-tests-tempest, networking-l2gw, trove-tempest-plugin, ironic-tempest-plugin,
+  cinder-tempest-plugin, manila-tempest-plugin, designate-tempest-plugin, octavia-tempest-plugin,
+  barbican-tempest-plugin, keystone-tempest-plugin, novajoin-tempest-plugin,
+  kuryr-tempest-plugin, magnum-tempest-plugin, mistral-tempest-plugin, murano-tempest-plugin,
+  patrole, watcher-tempest-plugin, zaqar-tempest-plugin, heat-tempest-plugin,
+  telemetry-tempest-plugin, sahara-tempest-plugin, sahara-tests, vitrage-tempest-plugin.`
+
 * `openstack-tempest-extras <https://quay.io/podified-antelope-centos9/openstack-tempest-extras>`_
 
+  An image that contains `tempest-stress` and `whitebox-tempest-plugin` on top of the all plugins
+  that are part of the `openstack-tempest-all` image.
+
+
 `test-operator` runs, for now, only the following test images:
 
-* openstack-tempest
+* `openstack-tempest <https://quay.io/podified-antelope-centos9/openstack-tempest>`_