ansible-community · felixfontein · Dec 1, 2022
diff --git a/changelogs/fragments/75-env-vars-modules.yml 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
@@ -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
@@ -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,23 +147,23 @@
 {%       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) %}
 
         :ansible-option-versionadded:`added in @{ version_added_rst(myvar['version_added'], myvar['version_added_collection'] or collection) }@`
 {%       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) %}
 
         :ansible-option-versionadded:`added in @{ version_added_rst(kw['version_added'], kw['version_added_collection'] or collection) }@`
 {%       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 @@
       <p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">@{ value['default'] | antsibull_to_json | escape | indent(6, blank=true) }@</code></p>
 {%   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']) %}
       <p class="ansible-option-line"><strong class="ansible-option-configuration">Configuration:</strong></p>
+{%     if plugin_type == 'module' and value['env'] %}
+      <p>The below environment variable{% if value['env'] | length > 1 %}s{% endif %} will be used on the host that executes this module.</p>
+{%     endif %}
       <ul class="simple">
 {%     if value['ini'] %}
       <li>
@@ -268,7 +275,7 @@
 @{       deprecates_html(env['deprecated'], collection, role_entrypoint=role_entrypoint) }@
       </li>
 {%     endfor %}
-{%     for myvar in value['vars'] %}
+{%     for myvar in value['vars'] | default([]) %}
       <li>
         <p>Variable: @{ myvar['name'] | escape }@</p>
 {%       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) }@
       </li>
 {%     endfor %}
-{%     for kw in value['keyword'] %}
+{%     for kw in value['keyword'] | default([]) %}
       <li>
         <p>Keyword: @{ kw['name'] | escape }@</p>
 {%       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) }@
       </li>
 {%     endfor %}
-{%     for mycli in value['cli'] %}
+{%     for mycli in value['cli'] | default([]) %}
       <li>
         <p>CLI argument: @{ mycli['option'] | escape }@</p>
 {%       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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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"
       }
      },