Skip to content

Commit e581253

Browse files
felixfonteinfelixfontein
committed
Allow modules to declare environment variable fallbacks.
1 parent fdc47d4 commit e581253

File tree

24 files changed

+382
-24
lines changed

24 files changed

+382
-24
lines changed

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

+2
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

+1-1
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 configuration 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

+13-8
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, role_entrypoint=role_entrypoint) }@
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, role_entrypoint=role_entrypoint) }@
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, role_entrypoint=role_entrypoint) }@
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, role_entrypoint=role_entrypoint) }@
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, role_entrypoint=role_entrypoint) }@
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, role_entrypoint=role_entrypoint) }@
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

+3-1
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/ansible-doc-cache-all.json

+24-1
Original file line numberDiff line numberDiff line change
@@ -1334,6 +1334,11 @@
13341334
},
13351335
"foo": {
13361336
"description": "The foo source.",
1337+
"env": [
1338+
{
1339+
"name": "ANSIBLE_FOO"
1340+
}
1341+
],
13371342
"required": true,
13381343
"type": "str"
13391344
},
@@ -1346,12 +1351,30 @@
13461351
"Whatever.",
13471352
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
13481353
],
1354+
"env": [
1355+
{
1356+
"name": "ANSIBLE_FOO"
1357+
},
1358+
{
1359+
"name": "ANSIBLE_BAR",
1360+
"version_added": "2.2.0"
1361+
},
1362+
{
1363+
"deprecated": {
1364+
"alternatives": "use C(ANSIBLE_BAR)",
1365+
"removed_from_collection": "ns2.col",
1366+
"version": "4.0.0",
1367+
"why": "Will be gone."
1368+
},
1369+
"name": "ANSIBLE_BAZ"
1370+
}
1371+
],
13491372
"required": true,
13501373
"type": "str"
13511374
}
13521375
},
13531376
"type": "dict",
1354-
"version_added": "2.0.0",
1377+
"version_added": "2.1.0",
13551378
"version_added_collection": "ns2.col"
13561379
}
13571380
},

‎tests/functional/ansible-doc-cache-ns2.col.json

+24-1
Original file line numberDiff line numberDiff line change
@@ -1099,6 +1099,11 @@
10991099
},
11001100
"foo": {
11011101
"description": "The foo source.",
1102+
"env": [
1103+
{
1104+
"name": "ANSIBLE_FOO"
1105+
}
1106+
],
11021107
"required": true,
11031108
"type": "str"
11041109
},
@@ -1111,12 +1116,30 @@
11111116
"Whatever.",
11121117
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
11131118
],
1119+
"env": [
1120+
{
1121+
"name": "ANSIBLE_FOO"
1122+
},
1123+
{
1124+
"name": "ANSIBLE_BAR",
1125+
"version_added": "2.2.0"
1126+
},
1127+
{
1128+
"deprecated": {
1129+
"alternatives": "use C(ANSIBLE_BAR)",
1130+
"removed_from_collection": "ns2.col",
1131+
"version": "4.0.0",
1132+
"why": "Will be gone."
1133+
},
1134+
"name": "ANSIBLE_BAZ"
1135+
}
1136+
],
11141137
"required": true,
11151138
"type": "str"
11161139
}
11171140
},
11181141
"type": "dict",
1119-
"version_added": "2.0.0",
1142+
"version_added": "2.1.0",
11201143
"version_added_collection": "ns2.col"
11211144
}
11221145
},

‎tests/functional/ansible-version.output

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
ansible [core 2.15.0b1.post0] (stable-2.15 8f0ddcba2c) last updated 2023/04/06 20:47:29 (GMT +200)
1+
ansible [core 2.16.0.dev0] (devel 88a380c8f0) last updated 2023/04/06 20:47:05 (GMT +200)
22
config file = None
33
configured module search path = ['<<<<<HOME>>>>>/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
44
ansible python module location = <<<<<ANSIBLE>>>>>

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

+27-1
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 configuration 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 \ :ansopt:`subfoo`\ is specified when \ :ansopt:`foo=bar`\ or \ :ansval:`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 \ :ansopt:`subfoo`\ is specified when \ :ansopt:`foo=bar`\ or \ :ansval:`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

+32-1
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,15 @@ Parameters
180180
The foo source.
181181

182182

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

185194
</div>
@@ -203,7 +212,7 @@ Parameters
203212

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

206-
:ansible-option-versionadded:`added in ns2.col 2.0.0`
215+
:ansible-option-versionadded:`added in ns2.col 2.1.0`
207216

208217

209218
.. raw:: html
@@ -255,6 +264,28 @@ Parameters
255264
Also required when \ :ansopt:`ns2.col.foo#module:subfoo`\ is specified when \ :ansopt:`ns2.col.foo#module:foo=bar`\ or \ :ansval:`baz`\ .
256265

257266

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

260291
</div>

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

+27-1
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 configuration 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 \ :ansopt:`subfoo`\ is specified when \ :ansopt:`foo=bar`\ or \ :ansval:`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 \ :ansopt:`subfoo`\ is specified when \ :ansopt:`foo=bar`\ or \ :ansval:`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

+32-1
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,15 @@ Parameters
180180
The foo source.
181181

182182

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

185194
</div>
@@ -203,7 +212,7 @@ Parameters
203212

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

206-
:ansible-option-versionadded:`added in ns2.col 2.0.0`
215+
:ansible-option-versionadded:`added in ns2.col 2.1.0`
207216

208217

209218
.. raw:: html
@@ -255,6 +264,28 @@ Parameters
255264
Also required when \ :ansopt:`ns2.col.foo#module:subfoo`\ is specified when \ :ansopt:`ns2.col.foo#module:foo=bar`\ or \ :ansval:`baz`\ .
256265

257266

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

260291
</div>

0 commit comments

Comments
 (0)