From 9e924595925e8f394ccce3b76fe8a6c59db464da Mon Sep 17 00:00:00 2001 From: Ian Wienand Date: Tue, 14 Apr 2020 11:03:49 +1000 Subject: [PATCH] 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 | 12 ++++++++++++ roles/ensure-bazelisk/README.rst | 15 +++++++++------ roles/ensure-pip/README.rst | 10 ++++++++++ roles/ensure-tox/README.rst | 24 ++++++++++++++---------- 4 files changed, 45 insertions(+), 16 deletions(-) diff --git a/doc/source/policy.rst b/doc/source/policy.rst index d19148ede..85f296cfe 100644 --- a/doc/source/policy.rst +++ b/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 ------- diff --git a/roles/ensure-bazelisk/README.rst b/roles/ensure-bazelisk/README.rst index 102d8ee4d..c787074af 100644 --- a/roles/ensure-bazelisk/README.rst +++ b/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. diff --git a/roles/ensure-pip/README.rst b/roles/ensure-pip/README.rst index 7797a6f33..243d4c2d7 100644 --- a/roles/ensure-pip/README.rst +++ b/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). diff --git a/roles/ensure-tox/README.rst b/roles/ensure-tox/README.rst index 1d1fd4af5..2ba02fde7 100644 --- a/roles/ensure-tox/README.rst +++ b/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.