cmd_runner_guide: docs improvements (#8963)

* cmd_runner_guide: docs improvements

* add note about suboptions

docs/docsite/rst/guide_cmdrunner.rst

@@ -68,20 +68,27 @@ This is meant to be done once, then every time you need to execute the command y
         with runner("version") as ctx:
             dummy, stdout, dummy = ctx.run()
 
+        # passes arg 'data' to AnsibleModule.run_command()
+        with runner("type name", data=stdin_data) as ctx:
+            dummy, stdout, dummy = ctx.run()
+
         # Another way of expressing it
         dummy, stdout, dummy = runner("version").run()
 
-Note that you can pass values for the arguments when calling ``run()``,
-otherwise ``CmdRunner`` uses the module options with the exact same names to
-provide values for the runner arguments. If no value is passed and no module option
-is found for the name specified, then an exception is raised, unless the
-argument is using ``cmd_runner_fmt.as_fixed`` as format function like the
-``version`` in the example above. See more about it below.
+Note that you can pass values for the arguments when calling ``run()``, otherwise ``CmdRunner``
+uses the module options with the exact same names to provide values for the runner arguments.
+If no value is passed and no module option is found for the name specified, then an exception is raised, unless
+the argument is using ``cmd_runner_fmt.as_fixed`` as format function like the ``version`` in the example above.
+See more about it below.
 
 In the first example, values of ``type``, ``force``, ``no_deps`` and others
 are taken straight from the module, whilst ``galaxy_cmd`` and ``upgrade`` are
 passed explicitly.
 
+.. note::
+
+    It is not possible to automatically retrieve values of suboptions.
+
 That generates a resulting command line similar to (example taken from the
 output of an integration test):
 
@@ -110,7 +117,7 @@ into something formatted for the command line.
 Argument format function
 """"""""""""""""""""""""
 
-An ``arg_format`` function should be of the form:
+An ``arg_format`` function is defined in the form similar to:
 
 .. code-block:: python
 
@@ -155,7 +162,7 @@ In these descriptions ``value`` refers to the single parameter passed to the for
 
     - Creation:
         ``cmd_runner_fmt.as_list()``
-    - Example:
+    - Examples:
         +----------------------+---------------------+
         | Value                | Outcome             |
         +======================+=====================+
@@ -167,27 +174,38 @@ In these descriptions ``value`` refers to the single parameter passed to the for
 - ``cmd_runner_fmt.as_bool()``
     This method receives two different parameters: ``args_true`` and ``args_false``, latter being optional.
     If the boolean evaluation of ``value`` is ``True``, the format function returns ``args_true``.
-    If the boolean evaluation is ``False``, then the function returns ``args_false``
-    if it was provided, or ``[]`` otherwise.
+    If the boolean evaluation is ``False``, then the function returns ``args_false`` if it was provided, or ``[]`` otherwise.
 
-    - Creation:
+    - Creation (one arg):
         ``cmd_runner_fmt.as_bool("--force")``
-    - Example:
+    - Examples:
         +------------+--------------------+
         | Value      | Outcome            |
         +============+====================+
         | ``True``   | ``["--force"]``    |
         +------------+--------------------+
         | ``False``  | ``[]``             |
         +------------+--------------------+
+    - Creation (two args):
+        ``cmd_runner_fmt.as_bool("--relax", "--dont-do-it")``
+    - Examples:
+        +------------+----------------------+
+        | Value      | Outcome              |
+        +============+======================+
+        | ``True``   | ``["--relax"]``      |
+        +------------+----------------------+
+        | ``False``  | ``["--dont-do-it"]`` |
+        +------------+----------------------+
+        |            | ``[]``               |
+        +------------+----------------------+
 
 - ``cmd_runner_fmt.as_bool_not()``
     This method receives one parameter, which is returned by the function when the boolean evaluation
     of ``value`` is ``False``.
 
     - Creation:
         ``cmd_runner_fmt.as_bool_not("--no-deps")``
-    - Example:
+    - Examples:
         +-------------+---------------------+
         | Value       | Outcome             |
         +=============+=====================+
@@ -202,7 +220,7 @@ In these descriptions ``value`` refers to the single parameter passed to the for
 
     - Creation:
         ``cmd_runner_fmt.as_optval("-i")``
-    - Example:
+    - Examples:
         +---------------+---------------------+
         | Value         | Outcome             |
         +===============+=====================+
@@ -216,7 +234,7 @@ In these descriptions ``value`` refers to the single parameter passed to the for
 
     - Creation:
         ``cmd_runner_fmt.as_opt_val("--name")``
-    - Example:
+    - Examples:
         +--------------+--------------------------+
         | Value        | Outcome                  |
         +==============+==========================+
@@ -229,7 +247,7 @@ In these descriptions ``value`` refers to the single parameter passed to the for
 
     - Creation:
         ``cmd_runner_fmt.as_opt_eq_val("--num-cpus")``
-    - Example:
+    - Examples:
         +------------+-------------------------+
         | Value      | Outcome                 |
         +============+=========================+
@@ -243,7 +261,7 @@ In these descriptions ``value`` refers to the single parameter passed to the for
 
     - Creation:
         ``cmd_runner_fmt.as_fixed("--version")``
-    - Example:
+    - Examples:
         +---------+-----------------------+
         | Value   | Outcome               |
         +=========+=======================+
@@ -265,7 +283,7 @@ In these descriptions ``value`` refers to the single parameter passed to the for
 
     - Creation:
         ``cmd_runner_fmt.as_map(dict(a=1, b=2, c=3), default=42)``
-    - Example:
+    - Examples:
         +---------------------+---------------+
         | Value               | Outcome       |
         +=====================+===============+
@@ -359,6 +377,8 @@ Settings that can be passed to the ``CmdRunner`` constructor are:
     Command to be executed. It can be a single string, the executable name, or a list
     of strings containing the executable name as the first element and, optionally, fixed parameters.
     Those parameters are used in all executions of the runner.
+    The *executable* pointed by this parameter (whether itself when ``str`` or its first element when ``list``) is
+    processed using ``AnsibleModule.get_bin_path()`` *unless* it is an absolute path or contains the character ``/``.
 - ``arg_formats: dict``
     Mapping of argument names to formatting functions.
 - ``default_args_order: str``
@@ -394,6 +414,10 @@ When creating a context, the additional settings that can be passed to the call
     Defaults to ``False``.
 - ``check_mode_return: any``
     If ``check_mode_skip=True``, then return this value instead.
+- valid named arguments to ``AnsibleModule.run_command()``
+    Other than ``args``, any valid argument to ``run_command()`` can be passed when setting up the run context.
+    For example, ``data`` can be used to send information to the command's standard input.
+    Or ``cwd`` can be used to run the command inside a specific working directory.
 
 Additionally, any other valid parameters for ``AnsibleModule.run_command()`` may be passed, but unexpected behavior
 might occur if redefining options already present in the runner or its context creation. Use with caution.