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) }@
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 %}Variable: @{ myvar['name'] | escape }@
{% if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection'] or collection) %} @@ -277,7 +284,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) %} @@ -286,7 +293,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 b8dcf535..9134491c 100644 --- a/src/antsibull_docs/schemas/docs/module.py +++ b/src/antsibull_docs/schemas/docs/module.py @@ -9,10 +9,16 @@ 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: list[OptionEnvSchema] = [] suboptions: dict[str, "InnerModuleOptionsSchema"] = {} @p.root_validator(pre=True) @@ -28,6 +34,7 @@ def allow_description_to_be_optional(cls, values): class ModuleOptionsSchema(OptionsSchema): + env: list[OptionEnvSchema] = [] suboptions: dict[str, "InnerModuleOptionsSchema"] = {} diff --git a/tests/functional/ansible-doc-cache-all-others.json b/tests/functional/ansible-doc-cache-all-others.json index 7bd3fc44..8f332978 100644 --- a/tests/functional/ansible-doc-cache-all-others.json +++ b/tests/functional/ansible-doc-cache-all-others.json @@ -23111,6 +23111,11 @@ }, "foo": { "description": "The foo source.", + "env": [ + { + "name": "ANSIBLE_FOO" + } + ], "required": true, "type": "str" }, @@ -23123,12 +23128,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-all.json b/tests/functional/ansible-doc-cache-all.json index 1d66c580..3c16165f 100644 --- a/tests/functional/ansible-doc-cache-all.json +++ b/tests/functional/ansible-doc-cache-all.json @@ -23030,6 +23030,11 @@ }, "foo": { "description": "The foo source.", + "env": [ + { + "name": "ANSIBLE_FOO" + } + ], "required": true, "type": "str" }, @@ -23042,12 +23047,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-ansible.builtin-ns.col2-ns2.col.json b/tests/functional/ansible-doc-cache-ansible.builtin-ns.col2-ns2.col.json index 60314327..0d7693c5 100644 --- a/tests/functional/ansible-doc-cache-ansible.builtin-ns.col2-ns2.col.json +++ b/tests/functional/ansible-doc-cache-ansible.builtin-ns.col2-ns2.col.json @@ -23030,6 +23030,11 @@ }, "foo": { "description": "The foo source.", + "env": [ + { + "name": "ANSIBLE_FOO" + } + ], "required": true, "type": "str" }, @@ -23042,12 +23047,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-ansible.builtin-ns2.col.json b/tests/functional/ansible-doc-cache-ansible.builtin-ns2.col.json index 73d6a745..3d48c0a7 100644 --- a/tests/functional/ansible-doc-cache-ansible.builtin-ns2.col.json +++ b/tests/functional/ansible-doc-cache-ansible.builtin-ns2.col.json @@ -22655,6 +22655,11 @@ }, "foo": { "description": "The foo source.", + "env": [ + { + "name": "ANSIBLE_FOO" + } + ], "required": true, "type": "str" }, @@ -22667,12 +22672,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-ns.col1-ns.col2-ns2.col-ns2.flatcol.json b/tests/functional/ansible-doc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json index e5ae147b..efa1b84e 100644 --- a/tests/functional/ansible-doc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json +++ b/tests/functional/ansible-doc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json @@ -1497,6 +1497,11 @@ }, "foo": { "description": "The foo source.", + "env": [ + { + "name": "ANSIBLE_FOO" + } + ], "required": true, "type": "str" }, @@ -1509,12 +1514,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-ns.col1-ns2.col-ns2.flatcol.json b/tests/functional/ansible-doc-cache-ns.col1-ns2.col-ns2.flatcol.json index 92aafbac..db92bec6 100644 --- a/tests/functional/ansible-doc-cache-ns.col1-ns2.col-ns2.flatcol.json +++ b/tests/functional/ansible-doc-cache-ns.col1-ns2.col-ns2.flatcol.json @@ -1122,6 +1122,11 @@ }, "foo": { "description": "The foo source.", + "env": [ + { + "name": "ANSIBLE_FOO" + } + ], "required": true, "type": "str" }, @@ -1134,12 +1139,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 4b0677ed..30092671 100644 --- a/tests/functional/ansible-doc-cache-ns2.col.json +++ b/tests/functional/ansible-doc-cache-ns2.col.json @@ -1122,6 +1122,11 @@ }, "foo": { "description": "The foo source.", + "env": [ + { + "name": "ANSIBLE_FOO" + } + ], "required": true, "type": "str" }, @@ -1134,12 +1139,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/baseline-default/collections/environment_variables.rst b/tests/functional/baseline-default/collections/environment_variables.rst index 7c10e9d7..41fdd87c 100644 --- a/tests/functional/baseline-default/collections/environment_variables.rst +++ b/tests/functional/baseline-default/collections/environment_variables.rst @@ -9,9 +9,35 @@ 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`. +.. envvar:: ANSIBLE_BAR + + A sub foo. + + Whatever. + + Also required when \ :ansopt:`subfoo`\ is specified when \ :ansopt:`foo=bar`\ or \ :ansval:`baz`\ . + + *Used by:* + :ansplugin:`ns2.col.foo moduledictionary
-added in ns2.col 2.0.0
+added in ns2.col 2.1.0
Some recursive foo.
diff --git a/tests/functional/baseline-simplified-rst/collections/ns2/col/foo_module.rst b/tests/functional/baseline-simplified-rst/collections/ns2/col/foo_module.rst index 47aa0a48..879271e1 100644 --- a/tests/functional/baseline-simplified-rst/collections/ns2/col/foo_module.rst +++ b/tests/functional/baseline-simplified-rst/collections/ns2/col/foo_module.rst @@ -95,7 +95,7 @@ Parametersdictionary
-added in ns2.col 2.0.0
+added in ns2.col 2.1.0
Some recursive foo.
diff --git a/tests/functional/baseline-squash-hierarchy/environment_variables.rst b/tests/functional/baseline-squash-hierarchy/environment_variables.rst index 7c10e9d7..41fdd87c 100644 --- a/tests/functional/baseline-squash-hierarchy/environment_variables.rst +++ b/tests/functional/baseline-squash-hierarchy/environment_variables.rst @@ -9,9 +9,35 @@ 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`. +.. envvar:: ANSIBLE_BAR + + A sub foo. + + Whatever. + + Also required when \ :ansopt:`subfoo`\ is specified when \ :ansopt:`foo=bar`\ or \ :ansval:`baz`\ . + + *Used by:* + :ansplugin:`ns2.col.foo moduleThe 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.
@@ -149,6 +157,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