docs/detailed_test_config: document ``--block`` option

Signed-off-by: Deepika Upadhyay <dupadhya@redhat.com>

diff --git a/docs/detailed_test_config.rst b/docs/detailed_test_config.rst
index 682f57fe9251ee618bb6e674f0b8a4fcbc462c62..3cce346b17f5169283da5149fd8f635c2f2b3de7 100644 (file)
--- a/docs/detailed_test_config.rst
+++ b/docs/detailed_test_config.rst
@@ -12,10 +12,6 @@ An integration test run takes three items of configuration:
 - ``targets``: what hosts to run on; this is a dictionary mapping
   hosts to ssh host keys, like:
   "username@hostname.example.com: ssh-rsa long_hostkey_here"
-  It is possible to configure your installation so that if the targets line
-  and host keys are omitted and teuthology is run with the --lock option,
-  then teuthology will grab machines from a pool of available
-  test machines.
 - ``roles``: how to use the hosts; this is a list of lists, where each
   entry lists all the roles to be run on a single host. For example, a
   single entry might say ``[mon.1, osd.1]``.
@@ -65,6 +61,14 @@ teuthology on it like this::
 
     ./virtualenv/bin/teuthology example.yaml
 
+It is possible to configure installation so that specifying targets and host
+keys can be omitted. Teuthology is run with the ``--lock`` option which locks
+the targets based on ``roles`` in YAML. Teuthology grabs machines from a pool of
+available test machines; but since most times machines are busy, you might have
+to wait until they are free or else command fails due to lack of available
+machines. To avoid this you can specify ``--block`` with ``--lock`` which will
+make teuthology retry until it finds and locks required machines.
+
 You could also pass the ``-v`` option for more verbose execution. See
 ``teuthology --help`` for more options.
 
@@ -97,7 +101,7 @@ lock command was run.
 You can override this with the ``--owner`` option when running
 teuthology or teuthology-lock.
 
-With teuthology-lock you can also add a description, so you can
+With ``teuthology-lock`` you can also add a description, so you can
 remember which tests you were running. This can be done when
 locking or unlocking machines, or as a separate action with the
 ``--update`` option. To lock 3 machines and set a description, run::
@@ -233,10 +237,10 @@ to explore the system as is. Adding a top-level::
     interactive-on-error: true
 
 as a config file for teuthology will make that possible. With that
-option, any *task* that fails, will have the ``interactive`` task
+option, any *task* that fails will have the ``interactive`` task
 called after it. This means that before any cleanup happens, you get a
 chance to inspect the system -- both through Teuthology and via extra
-SSH connections -- and the cleanup completes only when you choose so.
+SSH connections -- and the cleanup completes only when you choose.
 Just exit the interactive Python session to continue the cleanup.
 
 You can enable interactive-on-error with the ``teuthology`` command option