From 883482c82c696123f9775433ff230b6ed276a0bc Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 1 Dec 2022 07:12:19 +0100 Subject: [PATCH] Allow modules to declare environment variable fallbacks. --- changelogs/fragments/75-env-vars-modules.yml | 2 ++ .../list_of_env_variables.rst.j2 | 2 +- .../ansible-docsite/macros/parameters.rst.j2 | 23 ++++++++----- src/antsibull_docs/schemas/docs/module.py | 9 ++++- .../ansible-doc-cache-all-others.json | 25 +++++++++++++- tests/functional/ansible-doc-cache-all.json | 25 +++++++++++++- ...cache-ansible.builtin-ns.col2-ns2.col.json | 25 +++++++++++++- ...ble-doc-cache-ansible.builtin-ns2.col.json | 25 +++++++++++++- ...e-ns.col1-ns.col2-ns2.col-ns2.flatcol.json | 25 +++++++++++++- ...doc-cache-ns.col1-ns2.col-ns2.flatcol.json | 25 +++++++++++++- .../functional/ansible-doc-cache-ns2.col.json | 25 +++++++++++++- .../collections/environment_variables.rst | 28 +++++++++++++++- .../collections/ns2/col/foo_module.rst | 33 ++++++++++++++++++- .../collections/environment_variables.rst | 28 +++++++++++++++- .../collections/ns2/col/foo_module.rst | 33 ++++++++++++++++++- .../collections/environment_variables.rst | 28 +++++++++++++++- .../collections/ns2/col/foo_module.rst | 33 ++++++++++++++++++- .../foo_module.rst | 2 +- .../collections/ns2/col/foo_module.rst | 2 +- .../environment_variables.rst | 28 +++++++++++++++- .../baseline-squash-hierarchy/foo_module.rst | 33 ++++++++++++++++++- .../collections/environment_variables.rst | 28 +++++++++++++++- .../collections/ns2/col/foo_module.rst | 30 ++++++++++++++++- .../ns2/col/plugins/modules/foo.py | 15 ++++++++- .../schema/good_data/one_module_results.json | 2 ++ 25 files changed, 504 insertions(+), 30 deletions(-) create mode 100644 changelogs/fragments/75-env-vars-modules.yml diff --git a/changelogs/fragments/75-env-vars-modules.yml b/changelogs/fragments/75-env-vars-modules.yml new file mode 100644 index 00000000..529d9a80 --- /dev/null +++ b/changelogs/fragments/75-env-vars-modules.yml @@ -0,0 +1,2 @@ +minor_changes: + - "Allow modules to declare environment variables (https://github.com/ansible-community/antsibull-docs/pull/75)." diff --git a/src/antsibull_docs/data/docsite/ansible-docsite/list_of_env_variables.rst.j2 b/src/antsibull_docs/data/docsite/ansible-docsite/list_of_env_variables.rst.j2 index fc93bce1..4a2e1f82 100644 --- a/src/antsibull_docs/data/docsite/ansible-docsite/list_of_env_variables.rst.j2 +++ b/src/antsibull_docs/data/docsite/ansible-docsite/list_of_env_variables.rst.j2 @@ -14,7 +14,7 @@ Index of all Collection Environment Variables ============================================= -The following index documents all environment variables declared by plugins in collections. +The following index documents all environment variables declared by plugins and modules in collections. Environment variables used by the ansible-core configuration are documented in :ref:`ansible_configuration_settings`. {# TODO: use label `ansible_configuration_env_vars` once the ansible-core PR is merged #} diff --git a/src/antsibull_docs/data/docsite/ansible-docsite/macros/parameters.rst.j2 b/src/antsibull_docs/data/docsite/ansible-docsite/macros/parameters.rst.j2 index 1f01edb4..156bea1c 100644 --- a/src/antsibull_docs/data/docsite/ansible-docsite/macros/parameters.rst.j2 +++ b/src/antsibull_docs/data/docsite/ansible-docsite/macros/parameters.rst.j2 @@ -110,12 +110,16 @@ :ansible-option-default-bold:`Default:` :ansible-option-default:`@{ value['default'] | antsibull_to_json | rst_escape(escape_ending_whitespace=true) | indent(6, blank=true) }@` {% endif %} {# Configuration #} -{% if plugin_type != 'module' and plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['cli']) %} +{% if plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['cli']) %} .. rst-class:: ansible-option-line :ansible-option-configuration:`Configuration:` +{% if plugin_type == 'module' and value['env'] %} + The below environment variable{% if value['env'] | length > 1 %}s{% endif %} will be used on the host that executes this module. + +{% endif %} {% if value['ini'] %} - INI {% if value['ini'] | length == 1 %}entry{% else %}entries{% endif %}: {% for ini in value['ini'] %} @@ -143,7 +147,7 @@ {% endif %} @{ deprecates_rst(env['deprecated'], collection, 8, role_entrypoint=role_entrypoint) }@ {% endfor %} -{% for myvar in value['vars'] %} +{% for myvar in value['vars'] | default([]) %} - Variable: @{ myvar['name'] | rst_escape }@ {% if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection'] or collection) %} @@ -151,7 +155,7 @@ {% endif %} @{ deprecates_rst(myvar['deprecated'], collection, 8, role_entrypoint=role_entrypoint) }@ {% endfor %} -{% for kw in value['keyword'] %} +{% for kw in value['keyword'] | default([]) %} - Keyword: @{ kw['name'] | rst_escape }@ {% if kw['version_added'] is still_relevant(collection=kw['version_added_collection'] or collection) %} @@ -159,7 +163,7 @@ {% endif %} @{ deprecates_rst(kw['deprecated'], collection, 8, role_entrypoint=role_entrypoint) }@ {% endfor %} -{% for mycli in value['cli'] %} +{% for mycli in value['cli'] | default([]) %} - CLI argument: @{ mycli['option'] | rst_escape }@ {% if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection'] or collection) %} @@ -239,8 +243,11 @@

Default: @{ value['default'] | antsibull_to_json | escape | indent(6, blank=true) }@

{% endif %} {# Configuration #} -{% if plugin_type != 'module' and plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['cli']) %} +{% if plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['cli']) %}

Configuration:

+{% if plugin_type == 'module' and value['env'] %} +

The below environment variable{% if value['env'] | length > 1 %}s{% endif %} will be used on the host that executes this module.

+{% endif %}