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 07d05f18..0f837aa5 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) }@ {% 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) }@ {% 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) }@ {% 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) }@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) }@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 926a0e3c..69681c25 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/baseline-default/collections/environment_variables.rst b/tests/functional/baseline-default/collections/environment_variables.rst index bc0f4d6b..8561546d 100644 --- a/tests/functional/baseline-default/collections/environment_variables.rst +++ b/tests/functional/baseline-default/collections/environment_variables.rst @@ -6,9 +6,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:* + :ref:`ns2.col.foo moduleFoo 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 7fae7e20..2864be4b 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",