Allow modules to declare environment variable fallbacks.

Author: felixfontein

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)."

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 #}
 

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,23 +136,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) %}
 
@@ -228,8 +232,9 @@
       <p class="ansible-option-line"><span class="ansible-option-default-bold">Default:</span> <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"><span class="ansible-option-configuration">Configuration:</span></p>
+      <p>The below environment variable{% if value['env'] | length > 1 %}s{% endif %} will be used on the host that executes this module.</p>
       <ul class="simple">
 {%     if value['ini'] %}
       <li>
@@ -257,7 +262,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) %}
@@ -266,7 +271,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) %}
@@ -275,7 +280,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) %}

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'] = {}
 
 

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"
       }
      },

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"
       }
      },

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 module <ansible_collections.ns2.col.foo_module>`
+.. envvar:: ANSIBLE_BAZ
+
+    A sub foo.
+
+    Whatever.
+
+    Also required when \ :ansopt:`subfoo`\  is specified when \ :ansopt:`foo=bar`\  or \ :ansval:`baz`\ .
+
+    *Used by:*
+    :ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
+.. envvar:: ANSIBLE_FOO
+
+    See the documentations for the options where this environment variable is used.
+
+    *Used by:*
+    :ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
 .. envvar:: ANSIBLE_FOO_EXE
 
     Foo executable.

tests/functional/baseline-default/collections/ns2/col/foo_module.rst

@@ -180,6 +180,15 @@ Parameters
       The foo source.
 
 
+      .. rst-class:: ansible-option-line
+
+      :ansible-option-configuration:`Configuration:`
+
+      The below environment variable will be used on the host that executes this module.
+
+      - Environment variable: :envvar:`ANSIBLE\_FOO`
+
+
       .. raw:: html
 
         </div>
@@ -203,7 +212,7 @@ Parameters
 
       :ansible-option-type:`dictionary`
 
-      :ansible-option-versionadded:`added in ns2.col 2.0.0`
+      :ansible-option-versionadded:`added in ns2.col 2.1.0`
 
 
       .. raw:: html
@@ -255,6 +264,28 @@ Parameters
       Also required when \ :ansopt:`ns2.col.foo#module:subfoo`\  is specified when \ :ansopt:`ns2.col.foo#module:foo=bar`\  or \ :ansval:`baz`\ .
 
 
+      .. rst-class:: ansible-option-line
+
+      :ansible-option-configuration:`Configuration:`
+
+      The below environment variables will be used on the host that executes this module.
+
+      - Environment variable: :envvar:`ANSIBLE\_FOO`
+
+      - Environment variable: :envvar:`ANSIBLE\_BAR`
+
+        :ansible-option-versionadded:`added in ns2.col 2.2.0`
+
+      - Environment variable: :envvar:`ANSIBLE\_BAZ`
+
+        Removed in: version 4.0.0
+
+        Why: Will be gone.
+
+        Alternative: use \ :literal:`ANSIBLE\_BAR`\ 
+
+
+
       .. raw:: html
 
         </div>

tests/functional/baseline-no-breadcrumbs/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 module <ansible_collections.ns2.col.foo_module>`
+.. envvar:: ANSIBLE_BAZ
+
+    A sub foo.
+
+    Whatever.
+
+    Also required when \ :ansopt:`subfoo`\  is specified when \ :ansopt:`foo=bar`\  or \ :ansval:`baz`\ .
+
+    *Used by:*
+    :ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
+.. envvar:: ANSIBLE_FOO
+
+    See the documentations for the options where this environment variable is used.
+
+    *Used by:*
+    :ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
 .. envvar:: ANSIBLE_FOO_EXE
 
     Foo executable.

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_module.rst

@@ -180,6 +180,15 @@ Parameters
       The foo source.
 
 
+      .. rst-class:: ansible-option-line
+
+      :ansible-option-configuration:`Configuration:`
+
+      The below environment variable will be used on the host that executes this module.
+
+      - Environment variable: :envvar:`ANSIBLE\_FOO`
+
+
       .. raw:: html
 
         </div>
@@ -203,7 +212,7 @@ Parameters
 
       :ansible-option-type:`dictionary`
 
-      :ansible-option-versionadded:`added in ns2.col 2.0.0`
+      :ansible-option-versionadded:`added in ns2.col 2.1.0`
 
 
       .. raw:: html
@@ -255,6 +264,28 @@ Parameters
       Also required when \ :ansopt:`ns2.col.foo#module:subfoo`\  is specified when \ :ansopt:`ns2.col.foo#module:foo=bar`\  or \ :ansval:`baz`\ .
 
 
+      .. rst-class:: ansible-option-line
+
+      :ansible-option-configuration:`Configuration:`
+
+      The below environment variables will be used on the host that executes this module.
+
+      - Environment variable: :envvar:`ANSIBLE\_FOO`
+
+      - Environment variable: :envvar:`ANSIBLE\_BAR`
+
+        :ansible-option-versionadded:`added in ns2.col 2.2.0`
+
+      - Environment variable: :envvar:`ANSIBLE\_BAZ`
+
+        Removed in: version 4.0.0
+
+        Why: Will be gone.
+
+        Alternative: use \ :literal:`ANSIBLE\_BAR`\ 
+
+
+
       .. raw:: html
 
         </div>