Skip to content

Commit 2e9bf10

Browse files
felixfonteinfelixfontein
committed
Allow modules to declare environment variable fallbacks.
1 parent a0145df commit 2e9bf10

File tree

23 files changed

+386
-23
lines changed

23 files changed

+386
-23
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/ansible-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/ansible-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

+8-1
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,16 @@
99
import pydantic as p
1010

1111
from .base import BaseModel, DocSchema, OptionsSchema
12-
from .plugin import PluginExamplesSchema, PluginMetadataSchema, PluginReturnSchema
12+
from .plugin import (
13+
OptionEnvSchema,
14+
PluginExamplesSchema,
15+
PluginMetadataSchema,
16+
PluginReturnSchema,
17+
)
1318

1419

1520
class InnerModuleOptionsSchema(OptionsSchema):
21+
env: list[OptionEnvSchema] = []
1622
suboptions: dict[str, "InnerModuleOptionsSchema"] = {}
1723

1824
@p.root_validator(pre=True)
@@ -28,6 +34,7 @@ def allow_description_to_be_optional(cls, values):
2834

2935

3036
class ModuleOptionsSchema(OptionsSchema):
37+
env: list[OptionEnvSchema] = []
3138
suboptions: dict[str, "InnerModuleOptionsSchema"] = {}
3239

3340

‎tests/functional/ansible-doc-cache-all.json

+24-1
Original file line numberDiff line numberDiff line change
@@ -22909,6 +22909,11 @@
2290922909
},
2291022910
"foo": {
2291122911
"description": "The foo source.",
22912+
"env": [
22913+
{
22914+
"name": "ANSIBLE_FOO"
22915+
}
22916+
],
2291222917
"required": true,
2291322918
"type": "str"
2291422919
},
@@ -22921,12 +22926,30 @@
2292122926
"Whatever.",
2292222927
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
2292322928
],
22929+
"env": [
22930+
{
22931+
"name": "ANSIBLE_FOO"
22932+
},
22933+
{
22934+
"name": "ANSIBLE_BAR",
22935+
"version_added": "2.2.0"
22936+
},
22937+
{
22938+
"deprecated": {
22939+
"alternatives": "use C(ANSIBLE_BAR)",
22940+
"removed_from_collection": "ns2.col",
22941+
"version": "4.0.0",
22942+
"why": "Will be gone."
22943+
},
22944+
"name": "ANSIBLE_BAZ"
22945+
}
22946+
],
2292422947
"required": true,
2292522948
"type": "str"
2292622949
}
2292722950
},
2292822951
"type": "dict",
22929-
"version_added": "2.0.0",
22952+
"version_added": "2.1.0",
2293022953
"version_added_collection": "ns2.col"
2293122954
}
2293222955
},

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

+24-1
Original file line numberDiff line numberDiff line change
@@ -1122,6 +1122,11 @@
11221122
},
11231123
"foo": {
11241124
"description": "The foo source.",
1125+
"env": [
1126+
{
1127+
"name": "ANSIBLE_FOO"
1128+
}
1129+
],
11251130
"required": true,
11261131
"type": "str"
11271132
},
@@ -1134,12 +1139,30 @@
11341139
"Whatever.",
11351140
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
11361141
],
1142+
"env": [
1143+
{
1144+
"name": "ANSIBLE_FOO"
1145+
},
1146+
{
1147+
"name": "ANSIBLE_BAR",
1148+
"version_added": "2.2.0"
1149+
},
1150+
{
1151+
"deprecated": {
1152+
"alternatives": "use C(ANSIBLE_BAR)",
1153+
"removed_from_collection": "ns2.col",
1154+
"version": "4.0.0",
1155+
"why": "Will be gone."
1156+
},
1157+
"name": "ANSIBLE_BAZ"
1158+
}
1159+
],
11371160
"required": true,
11381161
"type": "str"
11391162
}
11401163
},
11411164
"type": "dict",
1142-
"version_added": "2.0.0",
1165+
"version_added": "2.1.0",
11431166
"version_added_collection": "ns2.col"
11441167
}
11451168
},

‎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
@@ -181,6 +181,15 @@ Parameters
181181
The foo source.
182182

183183

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

186195
</div>
@@ -204,7 +213,7 @@ Parameters
204213

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

207-
:ansible-option-versionadded:`added in ns2.col 2.0.0`
216+
:ansible-option-versionadded:`added in ns2.col 2.1.0`
208217

209218

210219
.. raw:: html
@@ -256,6 +265,28 @@ Parameters
256265
Also required when \ :ansopt:`ns2.col.foo#module:subfoo`\ is specified when \ :ansopt:`ns2.col.foo#module:foo=bar`\ or \ :ansval:`baz`\ .
257266

258267

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

261292
</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
@@ -181,6 +181,15 @@ Parameters
181181
The foo source.
182182

183183

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

186195
</div>
@@ -204,7 +213,7 @@ Parameters
204213

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

207-
:ansible-option-versionadded:`added in ns2.col 2.0.0`
216+
:ansible-option-versionadded:`added in ns2.col 2.1.0`
208217

209218

210219
.. raw:: html
@@ -256,6 +265,28 @@ Parameters
256265
Also required when \ :ansopt:`ns2.col.foo#module:subfoo`\ is specified when \ :ansopt:`ns2.col.foo#module:foo=bar`\ or \ :ansval:`baz`\ .
257266

258267

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

261292
</div>

0 commit comments

Comments
 (0)