Skip to content

Commit f91f1bb

Browse files
felixfonteinfelixfontein
committed
Allow modules to declare environment variable fallbacks.
1 parent 840bfe0 commit f91f1bb

File tree

21 files changed

+333
-21
lines changed

21 files changed

+333
-21
lines changed

‎changelogs/fragments/75-env-vars-modules.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
minor_changes:
2+
- "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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
Index of all Collection Environment Variables
1212
=============================================
1313

14-
The following index documents all environment variables declared by plugins in collections.
14+
The following index documents all environment variables declared by plugins and modules in collections.
1515
Environment variables used by the ansible-core configuation are documented in :ref:`ansible_configuration_settings`.
1616
{# TODO: use label `ansible_configuration_env_vars` once the ansible-core PR is merged #}
1717

‎src/antsibull_docs/data/docsite/macros/parameters.rst.j2

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -99,12 +99,16 @@
9999
:ansible-option-default-bold:`Default:` :ansible-option-default:`@{ value['default'] | antsibull_to_json | rst_escape(escape_ending_whitespace=true) | indent(6, blank=true) }@`
100100
{% endif %}
101101
{# Configuration #}
102-
{% if plugin_type != 'module' and plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['cli']) %}
102+
{% if plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['cli']) %}
103103

104104
.. rst-class:: ansible-option-line
105105

106106
:ansible-option-configuration:`Configuration:`
107107

108+
{% if plugin_type == 'module' and value['env'] %}
109+
The below environment variable{% if value['env'] | length > 1 %}s{% endif %} will be used on the host that executes this module.
110+
111+
{% endif %}
108112
{% if value['ini'] %}
109113
- INI {% if value['ini'] | length == 1 %}entry{% else %}entries{% endif %}:
110114
{% for ini in value['ini'] %}
@@ -132,23 +136,23 @@
132136
{% endif %}
133137
@{ deprecates_rst(env['deprecated'], collection, 8) }@
134138
{% endfor %}
135-
{% for myvar in value['vars'] %}
139+
{% for myvar in value['vars'] | default([]) %}
136140
- Variable: @{ myvar['name'] | rst_escape }@
137141
{% if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection'] or collection) %}
138142

139143
:ansible-option-versionadded:`added in @{ version_added_rst(myvar['version_added'], myvar['version_added_collection'] or collection) }@`
140144
{% endif %}
141145
@{ deprecates_rst(myvar['deprecated'], collection, 8) }@
142146
{% endfor %}
143-
{% for kw in value['keyword'] %}
147+
{% for kw in value['keyword'] | default([]) %}
144148
- Keyword: @{ kw['name'] | rst_escape }@
145149
{% if kw['version_added'] is still_relevant(collection=kw['version_added_collection'] or collection) %}
146150

147151
:ansible-option-versionadded:`added in @{ version_added_rst(kw['version_added'], kw['version_added_collection'] or collection) }@`
148152
{% endif %}
149153
@{ deprecates_rst(kw['deprecated'], collection, 8) }@
150154
{% endfor %}
151-
{% for mycli in value['cli'] %}
155+
{% for mycli in value['cli'] | default([]) %}
152156
- CLI argument: @{ mycli['option'] | rst_escape }@
153157
{% if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection'] or collection) %}
154158

@@ -228,8 +232,9 @@
228232
<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>
229233
{% endif %}
230234
{# Configuration #}
231-
{% if plugin_type != 'module' and plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['cli']) %}
235+
{% if plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['cli']) %}
232236
<p class="ansible-option-line"><span class="ansible-option-configuration">Configuration:</span></p>
237+
<p>The below environment variable{% if value['env'] | length > 1 %}s{% endif %} will be used on the host that executes this module.</p>
233238
<ul class="simple">
234239
{% if value['ini'] %}
235240
<li>
@@ -257,7 +262,7 @@
257262
@{ deprecates_html(env['deprecated'], collection) }@
258263
</li>
259264
{% endfor %}
260-
{% for myvar in value['vars'] %}
265+
{% for myvar in value['vars'] | default([]) %}
261266
<li>
262267
<p>Variable: @{ myvar['name'] | escape }@</p>
263268
{% if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection'] or collection) %}
@@ -266,7 +271,7 @@
266271
@{ deprecates_html(myvar['deprecated'], collection) }@
267272
</li>
268273
{% endfor %}
269-
{% for kw in value['keyword'] %}
274+
{% for kw in value['keyword'] | default([]) %}
270275
<li>
271276
<p>Keyword: @{ kw['name'] | escape }@</p>
272277
{% if kw['version_added'] is still_relevant(collection=kw['version_added_collection'] or collection) %}
@@ -275,7 +280,7 @@
275280
@{ deprecates_html(kw['deprecated'], collection) }@
276281
</li>
277282
{% endfor %}
278-
{% for mycli in value['cli'] %}
283+
{% for mycli in value['cli'] | default([]) %}
279284
<li>
280285
<p>CLI argument: @{ mycli['option'] | escape }@</p>
281286
{% if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection'] or collection) %}

‎src/antsibull_docs/schemas/docs/module.py

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,11 @@
1010
import pydantic as p
1111

1212
from .base import BaseModel, DocSchema, OptionsSchema
13-
from .plugin import PluginExamplesSchema, PluginMetadataSchema, PluginReturnSchema
13+
from .plugin import OptionEnvSchema, PluginExamplesSchema, PluginMetadataSchema, PluginReturnSchema
1414

1515

1616
class InnerModuleOptionsSchema(OptionsSchema):
17+
env: t.List[OptionEnvSchema] = []
1718
suboptions: t.Dict[str, 'InnerModuleOptionsSchema'] = {}
1819

1920
@p.root_validator(pre=True)
@@ -29,6 +30,7 @@ def allow_description_to_be_optional(cls, values):
2930

3031

3132
class ModuleOptionsSchema(OptionsSchema):
33+
env: t.List[OptionEnvSchema] = []
3234
suboptions: t.Dict[str, 'InnerModuleOptionsSchema'] = {}
3335

3436

‎tests/functional/baseline-default/collections/environment_variables.rst

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,35 @@
66
Index of all Collection Environment Variables
77
=============================================
88

9-
The following index documents all environment variables declared by plugins in collections.
9+
The following index documents all environment variables declared by plugins and modules in collections.
1010
Environment variables used by the ansible-core configuation are documented in :ref:`ansible_configuration_settings`.
1111

12+
.. envvar:: ANSIBLE_BAR
13+
14+
A sub foo.
15+
16+
Whatever.
17+
18+
Also required when \ :emphasis:`subfoo`\ is specified when \ :emphasis:`foo=bar`\ or \ :literal:`baz`\ .
19+
20+
*Used by:*
21+
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
22+
.. envvar:: ANSIBLE_BAZ
23+
24+
A sub foo.
25+
26+
Whatever.
27+
28+
Also required when \ :emphasis:`subfoo`\ is specified when \ :emphasis:`foo=bar`\ or \ :literal:`baz`\ .
29+
30+
*Used by:*
31+
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
32+
.. envvar:: ANSIBLE_FOO
33+
34+
See the documentations for the options where this environment variable is used.
35+
36+
*Used by:*
37+
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
1238
.. envvar:: ANSIBLE_FOO_EXE
1339

1440
Foo executable.

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

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,15 @@ Parameters
179179
The foo source.
180180

181181

182+
.. rst-class:: ansible-option-line
183+
184+
:ansible-option-configuration:`Configuration:`
185+
186+
The below environment variable will be used on the host that executes this module.
187+
188+
- Environment variable: :envvar:`ANSIBLE\_FOO`
189+
190+
182191
.. raw:: html
183192

184193
</div>
@@ -202,7 +211,7 @@ Parameters
202211

203212
:ansible-option-type:`dictionary`
204213

205-
:ansible-option-versionadded:`added in ns2.col 2.0.0`
214+
:ansible-option-versionadded:`added in ns2.col 2.1.0`
206215

207216

208217
.. raw:: html
@@ -254,6 +263,28 @@ Parameters
254263
Also required when \ :emphasis:`subfoo`\ is specified when \ :emphasis:`foo=bar`\ or \ :literal:`baz`\ .
255264

256265

266+
.. rst-class:: ansible-option-line
267+
268+
:ansible-option-configuration:`Configuration:`
269+
270+
The below environment variables will be used on the host that executes this module.
271+
272+
- Environment variable: :envvar:`ANSIBLE\_FOO`
273+
274+
- Environment variable: :envvar:`ANSIBLE\_BAR`
275+
276+
:ansible-option-versionadded:`added in ns2.col 2.2.0`
277+
278+
- Environment variable: :envvar:`ANSIBLE\_BAZ`
279+
280+
Removed in: version 4.0.0
281+
282+
Why: Will be gone.
283+
284+
Alternative: use \ :literal:`ANSIBLE\_BAR`\
285+
286+
287+
257288
.. raw:: html
258289

259290
</div>

‎tests/functional/baseline-no-breadcrumbs/collections/environment_variables.rst

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,35 @@
66
Index of all Collection Environment Variables
77
=============================================
88

9-
The following index documents all environment variables declared by plugins in collections.
9+
The following index documents all environment variables declared by plugins and modules in collections.
1010
Environment variables used by the ansible-core configuation are documented in :ref:`ansible_configuration_settings`.
1111

12+
.. envvar:: ANSIBLE_BAR
13+
14+
A sub foo.
15+
16+
Whatever.
17+
18+
Also required when \ :emphasis:`subfoo`\ is specified when \ :emphasis:`foo=bar`\ or \ :literal:`baz`\ .
19+
20+
*Used by:*
21+
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
22+
.. envvar:: ANSIBLE_BAZ
23+
24+
A sub foo.
25+
26+
Whatever.
27+
28+
Also required when \ :emphasis:`subfoo`\ is specified when \ :emphasis:`foo=bar`\ or \ :literal:`baz`\ .
29+
30+
*Used by:*
31+
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
32+
.. envvar:: ANSIBLE_FOO
33+
34+
See the documentations for the options where this environment variable is used.
35+
36+
*Used by:*
37+
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
1238
.. envvar:: ANSIBLE_FOO_EXE
1339

1440
Foo executable.

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

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,15 @@ Parameters
179179
The foo source.
180180

181181

182+
.. rst-class:: ansible-option-line
183+
184+
:ansible-option-configuration:`Configuration:`
185+
186+
The below environment variable will be used on the host that executes this module.
187+
188+
- Environment variable: :envvar:`ANSIBLE\_FOO`
189+
190+
182191
.. raw:: html
183192

184193
</div>
@@ -202,7 +211,7 @@ Parameters
202211

203212
:ansible-option-type:`dictionary`
204213

205-
:ansible-option-versionadded:`added in ns2.col 2.0.0`
214+
:ansible-option-versionadded:`added in ns2.col 2.1.0`
206215

207216

208217
.. raw:: html
@@ -254,6 +263,28 @@ Parameters
254263
Also required when \ :emphasis:`subfoo`\ is specified when \ :emphasis:`foo=bar`\ or \ :literal:`baz`\ .
255264

256265

266+
.. rst-class:: ansible-option-line
267+
268+
:ansible-option-configuration:`Configuration:`
269+
270+
The below environment variables will be used on the host that executes this module.
271+
272+
- Environment variable: :envvar:`ANSIBLE\_FOO`
273+
274+
- Environment variable: :envvar:`ANSIBLE\_BAR`
275+
276+
:ansible-option-versionadded:`added in ns2.col 2.2.0`
277+
278+
- Environment variable: :envvar:`ANSIBLE\_BAZ`
279+
280+
Removed in: version 4.0.0
281+
282+
Why: Will be gone.
283+
284+
Alternative: use \ :literal:`ANSIBLE\_BAR`\
285+
286+
287+
257288
.. raw:: html
258289

259290
</div>

‎tests/functional/baseline-no-indexes/collections/environment_variables.rst

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,35 @@
66
Index of all Collection Environment Variables
77
=============================================
88

9-
The following index documents all environment variables declared by plugins in collections.
9+
The following index documents all environment variables declared by plugins and modules in collections.
1010
Environment variables used by the ansible-core configuation are documented in :ref:`ansible_configuration_settings`.
1111

12+
.. envvar:: ANSIBLE_BAR
13+
14+
A sub foo.
15+
16+
Whatever.
17+
18+
Also required when \ :emphasis:`subfoo`\ is specified when \ :emphasis:`foo=bar`\ or \ :literal:`baz`\ .
19+
20+
*Used by:*
21+
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
22+
.. envvar:: ANSIBLE_BAZ
23+
24+
A sub foo.
25+
26+
Whatever.
27+
28+
Also required when \ :emphasis:`subfoo`\ is specified when \ :emphasis:`foo=bar`\ or \ :literal:`baz`\ .
29+
30+
*Used by:*
31+
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
32+
.. envvar:: ANSIBLE_FOO
33+
34+
See the documentations for the options where this environment variable is used.
35+
36+
*Used by:*
37+
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
1238
.. envvar:: ANSIBLE_FOO_EXE
1339

1440
Foo executable.

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

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,15 @@ Parameters
179179
The foo source.
180180

181181

182+
.. rst-class:: ansible-option-line
183+
184+
:ansible-option-configuration:`Configuration:`
185+
186+
The below environment variable will be used on the host that executes this module.
187+
188+
- Environment variable: :envvar:`ANSIBLE\_FOO`
189+
190+
182191
.. raw:: html
183192

184193
</div>
@@ -202,7 +211,7 @@ Parameters
202211

203212
:ansible-option-type:`dictionary`
204213

205-
:ansible-option-versionadded:`added in ns2.col 2.0.0`
214+
:ansible-option-versionadded:`added in ns2.col 2.1.0`
206215

207216

208217
.. raw:: html
@@ -254,6 +263,28 @@ Parameters
254263
Also required when \ :emphasis:`subfoo`\ is specified when \ :emphasis:`foo=bar`\ or \ :literal:`baz`\ .
255264

256265

266+
.. rst-class:: ansible-option-line
267+
268+
:ansible-option-configuration:`Configuration:`
269+
270+
The below environment variables will be used on the host that executes this module.
271+
272+
- Environment variable: :envvar:`ANSIBLE\_FOO`
273+
274+
- Environment variable: :envvar:`ANSIBLE\_BAR`
275+
276+
:ansible-option-versionadded:`added in ns2.col 2.2.0`
277+
278+
- Environment variable: :envvar:`ANSIBLE\_BAZ`
279+
280+
Removed in: version 4.0.0
281+
282+
Why: Will be gone.
283+
284+
Alternative: use \ :literal:`ANSIBLE\_BAR`\
285+
286+
287+
257288
.. raw:: html
258289

259290
</div>

0 commit comments

Comments
 (0)