From 515edd403543aacb2edc0698c12f6dfd6820141a Mon Sep 17 00:00:00 2001
From: Michel Peterson <michel@redhat.com>
Date: Thu, 21 Dec 2017 17:22:49 +0200
Subject: [PATCH] Document how to write multiline regex with comments

It is possible to add multiline and docummented regex to the
tempest_test_regex but it might not be evident at first, although very
useful for some scenarios.

This patch documents how this should be achieved to make it easier for
people in the future.

Change-Id: Id54679debedb1667cc70004b9a28fba921e50c0b
---
 roles/run-tempest/README.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/roles/run-tempest/README.rst b/roles/run-tempest/README.rst
index 001586e37f..b5defb724f 100644
--- a/roles/run-tempest/README.rst
+++ b/roles/run-tempest/README.rst
@@ -16,9 +16,19 @@ Run Tempest
    :default: ''
 
    A regular expression used to select the tests.
+
    It works only when used with some specific tox environments
    ('all', 'all-plugin'.)
 
+   Multi-line and commented regexs can be achieved by doing this:
+
+       ::
+           vars:
+             tempest_test_regex: |
+               (?x)    # Ignore comments and whitespaces
+               # Line with only a comment.
+               (tempest\.(api|scenario|thirdparty)).*$    # Run only api scenario and third party
+
 .. zuul:rolevar:: tox_venvlist
    :default: smoke