Document output variables

Several roles are setting facts that are expected to be consumed by
roles following them; generally things like the path to installed
tools, etc.

Add a section to policy about this behaviour in general, noting it
should use the cachable flags to persist the values.

Add specific documentation notes in an "Output Variable" section for
roles currently implementing this behaviour.

Change-Id: I05657fec198176c7d7345e84293f4902c81fa30c

doc/source/policy.rst

@@ -197,6 +197,18 @@ Here are the ways to install dependencies in order of preference:
 In any case, the role's documentation should mention which dependencies are
 needed, allowing users to prepare their hosts accordingly.
 
+Output Variables
+****************
+
+Some roles may find it useful to set a variable that can be consumed
+by later roles.  For example, the `ensure-pip` role sets a variable
+which specifies a working `virtualenv` command for the host.
+
+Roles should document their output under the **Output** section of
+their README documentation.  The variable should use the `cacheable:
+true` flag to `set_fact` to ensure that the variable is available
+across playbooks.
+
 Testing
 -------
 

roles/ensure-bazelisk/README.rst

@@ -21,14 +21,17 @@ home directory by default.
 
    The URL from which to download bazelisk.
 
-.. zuul:rolevar:: bazelisk_executable
-   :default: bazelisk
-
-   The bazelisk executable.  If this already exists, the
-   role will not perform any further actions.
-
 .. zuul:rolevar:: bazelisk_target
    :default: "{{ ansible_user_dir }}/.local/bin/bazelisk"
 
    Where to install bazelisk.  If the role downloads bazelisk, it will
    set :zuul:rolevar:`ensure-bazelisk.bazelisk_executable` to this value as well.
+
+**Output Variables**
+
+.. zuul:rolevar:: bazelisk_executable
+   :default: bazelisk
+
+   The bazelisk executable.  If this already exists, the role will not
+   perform any further actions.  It will be made available for other
+   roles running after role.

roles/ensure-pip/README.rst

@@ -49,3 +49,13 @@ qualified name (``pip2`` or ``pip3``) to avoid confusion.
    does not install the Python 2 interpreter, which may not be
    available on the system, so caution should be used when specifying
    ``python2`` in this list.
+
+**Output Variables**
+
+.. zuul:rolevar:: ensure_pip_virtualenv_cmd
+
+   This variable will be set to a command appropriate for general
+   usage with the `pip` module `virtualenv_command` argument on the
+   host.  On Python 3 hosts this will be the inbuilt `venv` module, on
+   Python 2 hosts the `virtualenv` package will be installed (this is
+   avoided on Python 3 hosts as an unnecessary dependency).

roles/ensure-tox/README.rst

@@ -3,18 +3,8 @@ Ensure tox is installed
 Look for ``tox``, and if not found, install it via ``pip`` in the user
 install directory (i.e., ``pip install --user``).
 
-After running this role, ``tox_executable`` will be set as the path to
-a valid ``tox``.
-
 **Role Variables**
 
-.. zuul:rolevar:: tox_executable
-   :default: ``tox``
-
-   Look for an existing ``tox`` at this specific path.  Note the
-   default (``tox``) effectively means to find tox in the current
-   ``$PATH``.
-
 .. zuul:rolevar:: tox_prefer_python2
    :default: ``false``
 
@@ -25,3 +15,17 @@ a valid ``tox``.
    :zuul:rolevar:`ensure-pip.ensure_pip_from_packages_with_python2`
    will be automatically set to `True` to enable a Python 2
    installation of `pip`.
+
+**Output Variables**
+
+.. zuul:rolevar:: tox_executable
+   :default: ``tox``
+
+   After running this role, ``tox_executable`` will be set as the path
+   to a valid ``tox``.
+
+   At role runtime, look for an existing ``tox`` at this specific
+   path.  Note the default (``tox``) effectively means to find tox in
+   the current ``$PATH``.  For example, if your base image
+   pre-installs tox in an out-of-path environment, set this so the
+   role does not attempt to install the user version.