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) }@
 {%     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) }@
 {%     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) }@
 {%     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) }@
       </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) }@
       </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) }@
       </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

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

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>

tests/functional/baseline-no-indexes/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-indexes/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>