Skip to content

Commit 883482c

Browse files
felixfonteinfelixfontein
committed
Allow modules to declare environment variable fallbacks.
1 parent 60de5f1 commit 883482c

File tree

25 files changed

+504
-30
lines changed

25 files changed

+504
-30
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/ansible-docsite/list_of_env_variables.rst.j2‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
Index of all Collection Environment Variables
1515
=============================================
1616

17-
The following index documents all environment variables declared by plugins in collections.
17+
The following index documents all environment variables declared by plugins and modules in collections.
1818
Environment variables used by the ansible-core configuration are documented in :ref:`ansible_configuration_settings`.
1919
{# TODO: use label `ansible_configuration_env_vars` once the ansible-core PR is merged #}
2020

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

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

115115
.. rst-class:: ansible-option-line
116116

117117
:ansible-option-configuration:`Configuration:`
118118

119+
{% if plugin_type == 'module' and value['env'] %}
120+
The below environment variable{% if value['env'] | length > 1 %}s{% endif %} will be used on the host that executes this module.
121+
122+
{% endif %}
119123
{% if value['ini'] %}
120124
- INI {% if value['ini'] | length == 1 %}entry{% else %}entries{% endif %}:
121125
{% for ini in value['ini'] %}
@@ -143,23 +147,23 @@
143147
{% endif %}
144148
@{ deprecates_rst(env['deprecated'], collection, 8, role_entrypoint=role_entrypoint) }@
145149
{% endfor %}
146-
{% for myvar in value['vars'] %}
150+
{% for myvar in value['vars'] | default([]) %}
147151
- Variable: @{ myvar['name'] | rst_escape }@
148152
{% if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection'] or collection) %}
149153

150154
:ansible-option-versionadded:`added in @{ version_added_rst(myvar['version_added'], myvar['version_added_collection'] or collection) }@`
151155
{% endif %}
152156
@{ deprecates_rst(myvar['deprecated'], collection, 8, role_entrypoint=role_entrypoint) }@
153157
{% endfor %}
154-
{% for kw in value['keyword'] %}
158+
{% for kw in value['keyword'] | default([]) %}
155159
- Keyword: @{ kw['name'] | rst_escape }@
156160
{% if kw['version_added'] is still_relevant(collection=kw['version_added_collection'] or collection) %}
157161

158162
:ansible-option-versionadded:`added in @{ version_added_rst(kw['version_added'], kw['version_added_collection'] or collection) }@`
159163
{% endif %}
160164
@{ deprecates_rst(kw['deprecated'], collection, 8, role_entrypoint=role_entrypoint) }@
161165
{% endfor %}
162-
{% for mycli in value['cli'] %}
166+
{% for mycli in value['cli'] | default([]) %}
163167
- CLI argument: @{ mycli['option'] | rst_escape }@
164168
{% if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection'] or collection) %}
165169

@@ -239,8 +243,11 @@
239243
<p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">@{ value['default'] | antsibull_to_json | escape | indent(6, blank=true) }@</code></p>
240244
{% endif %}
241245
{# Configuration #}
242-
{% if plugin_type != 'module' and plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['cli']) %}
246+
{% if plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['cli']) %}
243247
<p class="ansible-option-line"><strong class="ansible-option-configuration">Configuration:</strong></p>
248+
{% if plugin_type == 'module' and value['env'] %}
249+
<p>The below environment variable{% if value['env'] | length > 1 %}s{% endif %} will be used on the host that executes this module.</p>
250+
{% endif %}
244251
<ul class="simple">
245252
{% if value['ini'] %}
246253
<li>
@@ -268,7 +275,7 @@
268275
@{ deprecates_html(env['deprecated'], collection, role_entrypoint=role_entrypoint) }@
269276
</li>
270277
{% endfor %}
271-
{% for myvar in value['vars'] %}
278+
{% for myvar in value['vars'] | default([]) %}
272279
<li>
273280
<p>Variable: @{ myvar['name'] | escape }@</p>
274281
{% if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection'] or collection) %}
@@ -277,7 +284,7 @@
277284
@{ deprecates_html(myvar['deprecated'], collection, role_entrypoint=role_entrypoint) }@
278285
</li>
279286
{% endfor %}
280-
{% for kw in value['keyword'] %}
287+
{% for kw in value['keyword'] | default([]) %}
281288
<li>
282289
<p>Keyword: @{ kw['name'] | escape }@</p>
283290
{% if kw['version_added'] is still_relevant(collection=kw['version_added_collection'] or collection) %}
@@ -286,7 +293,7 @@
286293
@{ deprecates_html(kw['deprecated'], collection, role_entrypoint=role_entrypoint) }@
287294
</li>
288295
{% endfor %}
289-
{% for mycli in value['cli'] %}
296+
{% for mycli in value['cli'] | default([]) %}
290297
<li>
291298
<p>CLI argument: @{ mycli['option'] | escape }@</p>
292299
{% if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection'] or collection) %}

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

Lines changed: 8 additions & 1 deletion
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-others.json‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23111,6 +23111,11 @@
2311123111
},
2311223112
"foo": {
2311323113
"description": "The foo source.",
23114+
"env": [
23115+
{
23116+
"name": "ANSIBLE_FOO"
23117+
}
23118+
],
2311423119
"required": true,
2311523120
"type": "str"
2311623121
},
@@ -23123,12 +23128,30 @@
2312323128
"Whatever.",
2312423129
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
2312523130
],
23131+
"env": [
23132+
{
23133+
"name": "ANSIBLE_FOO"
23134+
},
23135+
{
23136+
"name": "ANSIBLE_BAR",
23137+
"version_added": "2.2.0"
23138+
},
23139+
{
23140+
"deprecated": {
23141+
"alternatives": "use C(ANSIBLE_BAR)",
23142+
"removed_from_collection": "ns2.col",
23143+
"version": "4.0.0",
23144+
"why": "Will be gone."
23145+
},
23146+
"name": "ANSIBLE_BAZ"
23147+
}
23148+
],
2312623149
"required": true,
2312723150
"type": "str"
2312823151
}
2312923152
},
2313023153
"type": "dict",
23131-
"version_added": "2.0.0",
23154+
"version_added": "2.1.0",
2313223155
"version_added_collection": "ns2.col"
2313323156
}
2313423157
},

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

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23030,6 +23030,11 @@
2303023030
},
2303123031
"foo": {
2303223032
"description": "The foo source.",
23033+
"env": [
23034+
{
23035+
"name": "ANSIBLE_FOO"
23036+
}
23037+
],
2303323038
"required": true,
2303423039
"type": "str"
2303523040
},
@@ -23042,12 +23047,30 @@
2304223047
"Whatever.",
2304323048
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
2304423049
],
23050+
"env": [
23051+
{
23052+
"name": "ANSIBLE_FOO"
23053+
},
23054+
{
23055+
"name": "ANSIBLE_BAR",
23056+
"version_added": "2.2.0"
23057+
},
23058+
{
23059+
"deprecated": {
23060+
"alternatives": "use C(ANSIBLE_BAR)",
23061+
"removed_from_collection": "ns2.col",
23062+
"version": "4.0.0",
23063+
"why": "Will be gone."
23064+
},
23065+
"name": "ANSIBLE_BAZ"
23066+
}
23067+
],
2304523068
"required": true,
2304623069
"type": "str"
2304723070
}
2304823071
},
2304923072
"type": "dict",
23050-
"version_added": "2.0.0",
23073+
"version_added": "2.1.0",
2305123074
"version_added_collection": "ns2.col"
2305223075
}
2305323076
},

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

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23030,6 +23030,11 @@
2303023030
},
2303123031
"foo": {
2303223032
"description": "The foo source.",
23033+
"env": [
23034+
{
23035+
"name": "ANSIBLE_FOO"
23036+
}
23037+
],
2303323038
"required": true,
2303423039
"type": "str"
2303523040
},
@@ -23042,12 +23047,30 @@
2304223047
"Whatever.",
2304323048
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
2304423049
],
23050+
"env": [
23051+
{
23052+
"name": "ANSIBLE_FOO"
23053+
},
23054+
{
23055+
"name": "ANSIBLE_BAR",
23056+
"version_added": "2.2.0"
23057+
},
23058+
{
23059+
"deprecated": {
23060+
"alternatives": "use C(ANSIBLE_BAR)",
23061+
"removed_from_collection": "ns2.col",
23062+
"version": "4.0.0",
23063+
"why": "Will be gone."
23064+
},
23065+
"name": "ANSIBLE_BAZ"
23066+
}
23067+
],
2304523068
"required": true,
2304623069
"type": "str"
2304723070
}
2304823071
},
2304923072
"type": "dict",
23050-
"version_added": "2.0.0",
23073+
"version_added": "2.1.0",
2305123074
"version_added_collection": "ns2.col"
2305223075
}
2305323076
},

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

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22655,6 +22655,11 @@
2265522655
},
2265622656
"foo": {
2265722657
"description": "The foo source.",
22658+
"env": [
22659+
{
22660+
"name": "ANSIBLE_FOO"
22661+
}
22662+
],
2265822663
"required": true,
2265922664
"type": "str"
2266022665
},
@@ -22667,12 +22672,30 @@
2266722672
"Whatever.",
2266822673
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
2266922674
],
22675+
"env": [
22676+
{
22677+
"name": "ANSIBLE_FOO"
22678+
},
22679+
{
22680+
"name": "ANSIBLE_BAR",
22681+
"version_added": "2.2.0"
22682+
},
22683+
{
22684+
"deprecated": {
22685+
"alternatives": "use C(ANSIBLE_BAR)",
22686+
"removed_from_collection": "ns2.col",
22687+
"version": "4.0.0",
22688+
"why": "Will be gone."
22689+
},
22690+
"name": "ANSIBLE_BAZ"
22691+
}
22692+
],
2267022693
"required": true,
2267122694
"type": "str"
2267222695
}
2267322696
},
2267422697
"type": "dict",
22675-
"version_added": "2.0.0",
22698+
"version_added": "2.1.0",
2267622699
"version_added_collection": "ns2.col"
2267722700
}
2267822701
},

‎tests/functional/ansible-doc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1497,6 +1497,11 @@
14971497
},
14981498
"foo": {
14991499
"description": "The foo source.",
1500+
"env": [
1501+
{
1502+
"name": "ANSIBLE_FOO"
1503+
}
1504+
],
15001505
"required": true,
15011506
"type": "str"
15021507
},
@@ -1509,12 +1514,30 @@
15091514
"Whatever.",
15101515
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
15111516
],
1517+
"env": [
1518+
{
1519+
"name": "ANSIBLE_FOO"
1520+
},
1521+
{
1522+
"name": "ANSIBLE_BAR",
1523+
"version_added": "2.2.0"
1524+
},
1525+
{
1526+
"deprecated": {
1527+
"alternatives": "use C(ANSIBLE_BAR)",
1528+
"removed_from_collection": "ns2.col",
1529+
"version": "4.0.0",
1530+
"why": "Will be gone."
1531+
},
1532+
"name": "ANSIBLE_BAZ"
1533+
}
1534+
],
15121535
"required": true,
15131536
"type": "str"
15141537
}
15151538
},
15161539
"type": "dict",
1517-
"version_added": "2.0.0",
1540+
"version_added": "2.1.0",
15181541
"version_added_collection": "ns2.col"
15191542
}
15201543
},

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

Lines changed: 24 additions & 1 deletion
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
},

0 commit comments

Comments
 (0)