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/list_of_env_variables.rst.j2 b/src/antsibull_docs/data/docsite/list_of_env_variables.rst.j2 index 6d6f27a0..261791b0 100644 --- a/src/antsibull_docs/data/docsite/list_of_env_variables.rst.j2 +++ b/src/antsibull_docs/data/docsite/list_of_env_variables.rst.j2 @@ -11,7 +11,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/macros/parameters.rst.j2 b/src/antsibull_docs/data/docsite/macros/parameters.rst.j2 index 72c73b33..e9232703 100644 --- a/src/antsibull_docs/data/docsite/macros/parameters.rst.j2 +++ b/src/antsibull_docs/data/docsite/macros/parameters.rst.j2 @@ -99,12 +99,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'] %} @@ -132,7 +136,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) %} @@ -140,7 +144,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) %} @@ -148,7 +152,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) %} @@ -228,8 +232,9 @@
Default: @{ value['default'] | antsibull_to_json | escape | indent(6, blank=true) }@
Configuration:
+The below environment variable{% if value['env'] | length > 1 %}s{% endif %} will be used on the host that executes this module.
Variable: @{ myvar['name'] | escape }@
{% if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection'] or collection) %} @@ -266,7 +271,7 @@ @{ deprecates_html(myvar['deprecated'], collection, role_entrypoint=role_entrypoint) }@Keyword: @{ kw['name'] | escape }@
{% if kw['version_added'] is still_relevant(collection=kw['version_added_collection'] or collection) %} @@ -275,7 +280,7 @@ @{ deprecates_html(kw['deprecated'], collection, role_entrypoint=role_entrypoint) }@CLI argument: @{ mycli['option'] | escape }@
{% if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection'] or collection) %} diff --git a/src/antsibull_docs/schemas/docs/module.py b/src/antsibull_docs/schemas/docs/module.py index afb0df3b..90e928cc 100644 --- a/src/antsibull_docs/schemas/docs/module.py +++ b/src/antsibull_docs/schemas/docs/module.py @@ -10,10 +10,11 @@ import pydantic as p from .base import BaseModel, DocSchema, OptionsSchema -from .plugin import PluginExamplesSchema, PluginMetadataSchema, PluginReturnSchema +from .plugin import OptionEnvSchema, PluginExamplesSchema, PluginMetadataSchema, PluginReturnSchema class InnerModuleOptionsSchema(OptionsSchema): + env: t.List[OptionEnvSchema] = [] suboptions: t.Dict[str, 'InnerModuleOptionsSchema'] = {} @p.root_validator(pre=True) @@ -29,6 +30,7 @@ def allow_description_to_be_optional(cls, values): class ModuleOptionsSchema(OptionsSchema): + env: t.List[OptionEnvSchema] = [] suboptions: t.Dict[str, 'InnerModuleOptionsSchema'] = {} diff --git a/tests/functional/ansible-doc-cache-all.json b/tests/functional/ansible-doc-cache-all.json index e3c22086..60d6a6bd 100644 --- a/tests/functional/ansible-doc-cache-all.json +++ b/tests/functional/ansible-doc-cache-all.json @@ -1334,6 +1334,11 @@ }, "foo": { "description": "The foo source.", + "env": [ + { + "name": "ANSIBLE_FOO" + } + ], "required": true, "type": "str" }, @@ -1346,12 +1351,30 @@ "Whatever.", "Also required when O(subfoo) is specified when O(foo=bar) or V(baz)." ], + "env": [ + { + "name": "ANSIBLE_FOO" + }, + { + "name": "ANSIBLE_BAR", + "version_added": "2.2.0" + }, + { + "deprecated": { + "alternatives": "use C(ANSIBLE_BAR)", + "removed_from_collection": "ns2.col", + "version": "4.0.0", + "why": "Will be gone." + }, + "name": "ANSIBLE_BAZ" + } + ], "required": true, "type": "str" } }, "type": "dict", - "version_added": "2.0.0", + "version_added": "2.1.0", "version_added_collection": "ns2.col" } }, diff --git a/tests/functional/ansible-doc-cache-ns2.col.json b/tests/functional/ansible-doc-cache-ns2.col.json index 50c437fe..3d00f74b 100644 --- a/tests/functional/ansible-doc-cache-ns2.col.json +++ b/tests/functional/ansible-doc-cache-ns2.col.json @@ -1099,6 +1099,11 @@ }, "foo": { "description": "The foo source.", + "env": [ + { + "name": "ANSIBLE_FOO" + } + ], "required": true, "type": "str" }, @@ -1111,12 +1116,30 @@ "Whatever.", "Also required when O(subfoo) is specified when O(foo=bar) or V(baz)." ], + "env": [ + { + "name": "ANSIBLE_FOO" + }, + { + "name": "ANSIBLE_BAR", + "version_added": "2.2.0" + }, + { + "deprecated": { + "alternatives": "use C(ANSIBLE_BAR)", + "removed_from_collection": "ns2.col", + "version": "4.0.0", + "why": "Will be gone." + }, + "name": "ANSIBLE_BAZ" + } + ], "required": true, "type": "str" } }, "type": "dict", - "version_added": "2.0.0", + "version_added": "2.1.0", "version_added_collection": "ns2.col" } }, diff --git a/tests/functional/ansible-version.output b/tests/functional/ansible-version.output index 6ecde2c9..83745113 100644 --- a/tests/functional/ansible-version.output +++ b/tests/functional/ansible-version.output @@ -1,4 +1,4 @@ -ansible [core 2.15.0b1.post0] (stable-2.15 8f0ddcba2c) last updated 2023/04/06 20:47:29 (GMT +200) +ansible [core 2.16.0.dev0] (devel 88a380c8f0) last updated 2023/04/06 20:47:05 (GMT +200) config file = None configured module search path = ['<<<<Foo executable.
Default: "foo"
Configuration:
+The below environment variables will be used on the host that executes this module.
INI entries
@@ -184,6 +185,7 @@ ParametersUser you 'become' to execute the task.
Default: "root"
Configuration:
+The below environment variables will be used on the host that executes this module.
INI entries
diff --git a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_cache.rst b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_cache.rst index 601c500a..c5ac4d3e 100644 --- a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_cache.rst +++ b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_cache.rst @@ -109,6 +109,7 @@ ParametersPath in which the cache plugin will save the foo files.
Configuration:
+The below environment variable will be used on the host that executes this module.
INI entry
diff --git a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_connection.rst b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_connection.rst index 663a95d4..40c24d1f 100644 --- a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_connection.rst +++ b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_connection.rst @@ -123,6 +123,7 @@ ParametersHostname to connect to.
Default: "inventory_hostname"
Configuration:
+The below environment variable will be used on the host that executes this module.
Variable: inventory_hostname
diff --git a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_module.rst b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_module.rst index cabbfb21..43309457 100644 --- a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_module.rst +++ b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_module.rst @@ -136,6 +136,14 @@ ParametersThe foo source.
+Configuration:
+The below environment variable will be used on the host that executes this module.
+Environment variable: ANSIBLE_FOO
dictionary
-added in ns2.col 2.0.0
+added in ns2.col 2.1.0
Some recursive foo.
@@ -166,6 +174,26 @@ ParametersA sub foo.
Whatever.
Also required when subfoo
is specified when foo=bar
or baz
.
Configuration:
+The below environment variables will be used on the host that executes this module.
+Environment variable: ANSIBLE_FOO
Environment variable: ANSIBLE_BAR
added in ns2.col 2.2.0
+ +Environment variable: ANSIBLE_BAZ
Removed in: version 4.0.0
+Why: Will be gone.
+Alternative: use ANSIBLE_BAR
Temporary directory to use on targets when executing tasks.
Default: "~/.ansible/tmp"
Configuration:
+The below environment variables will be used on the host that executes this module.
INI entry
diff --git a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_vars.rst b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_vars.rst index 871dfced..ed0f3c47 100644 --- a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_vars.rst +++ b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_vars.rst @@ -121,6 +121,7 @@ ParametersAll extensions to check.
Default: [".foo", ".foobar"]
Configuration:
+The below environment variable will be used on the host that executes this module.
INI entry
diff --git a/tests/functional/collections/ansible_collections/ns2/col/plugins/modules/foo.py b/tests/functional/collections/ansible_collections/ns2/col/plugins/modules/foo.py index 6e367124..931b1d8c 100644 --- a/tests/functional/collections/ansible_collections/ns2/col/plugins/modules/foo.py +++ b/tests/functional/collections/ansible_collections/ns2/col/plugins/modules/foo.py @@ -24,6 +24,8 @@ description: The foo source. type: str required: true + env: + - name: ANSIBLE_FOO bar: description: - A bar. @@ -35,7 +37,7 @@ - baz subfoo: description: Some recursive foo. - version_added: 2.0.0 + version_added: 2.1.0 type: dict suboptions: foo: @@ -45,6 +47,17 @@ - Also required when O(subfoo) is specified when O(foo=bar) or V(baz). type: str required: true + env: + - name: ANSIBLE_FOO + - name: ANSIBLE_BAR + version_added: 2.2.0 + - name: ANSIBLE_BAZ + deprecated: + why: Will be gone. + version: 4.0.0 + alternatives: use C(ANSIBLE_BAR) + # TODO: remove once ansible-core supports env variable docs for modules + removed_from_collection: ns2.col requirements: - Foo on remote. diff --git a/tests/functional/schema/good_data/one_module_results.json b/tests/functional/schema/good_data/one_module_results.json index 6427467b..a9f68b8d 100644 --- a/tests/functional/schema/good_data/one_module_results.json +++ b/tests/functional/schema/good_data/one_module_results.json @@ -214,6 +214,7 @@ "The groups to add the hostname to." ], "elements": "str", + "env": [], "required": false, "suboptions": {}, "type": "list", @@ -231,6 +232,7 @@ "The hostname/ip of the host to add to the inventory, can include a colon and a port number." ], "elements": "str", + "env": [], "required": true, "suboptions": {}, "type": "str",