Skip to content

Commit

Permalink
Allow modules to declare environment variable fallbacks.
Browse files Browse the repository at this point in the history
  • Loading branch information
felixfontein committed Sep 25, 2023
1 parent 60de5f1 commit 883482c
Show file tree
Hide file tree
Showing 25 changed files with 504 additions and 30 deletions.
2 changes: 2 additions & 0 deletions changelogs/fragments/75-env-vars-modules.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
minor_changes:
- "Allow modules to declare environment variables (https://github.com/ansible-community/antsibull-docs/pull/75)."
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,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 #}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -110,12 +110,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'] %}
Expand Down Expand Up @@ -143,23 +147,23 @@
{% endif %}
@{ deprecates_rst(env['deprecated'], collection, 8, role_entrypoint=role_entrypoint) }@
{% 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, role_entrypoint=role_entrypoint) }@
{% 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, role_entrypoint=role_entrypoint) }@
{% 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) %}

Expand Down Expand Up @@ -239,8 +243,11 @@
<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>
{% 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"><strong class="ansible-option-configuration">Configuration:</strong></p>
{% if plugin_type == 'module' and value['env'] %}
<p>The below environment variable{% if value['env'] | length > 1 %}s{% endif %} will be used on the host that executes this module.</p>
{% endif %}
<ul class="simple">
{% if value['ini'] %}
<li>
Expand Down Expand Up @@ -268,7 +275,7 @@
@{ deprecates_html(env['deprecated'], collection, role_entrypoint=role_entrypoint) }@
</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) %}
Expand All @@ -277,7 +284,7 @@
@{ deprecates_html(myvar['deprecated'], collection, role_entrypoint=role_entrypoint) }@
</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) %}
Expand All @@ -286,7 +293,7 @@
@{ deprecates_html(kw['deprecated'], collection, role_entrypoint=role_entrypoint) }@
</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) %}
Expand Down
9 changes: 8 additions & 1 deletion src/antsibull_docs/schemas/docs/module.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,16 @@
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: list[OptionEnvSchema] = []
suboptions: dict[str, "InnerModuleOptionsSchema"] = {}

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


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


Expand Down
25 changes: 24 additions & 1 deletion tests/functional/ansible-doc-cache-all-others.json
Original file line number Diff line number Diff line change
Expand Up @@ -23111,6 +23111,11 @@
},
"foo": {
"description": "The foo source.",
"env": [
{
"name": "ANSIBLE_FOO"
}
],
"required": true,
"type": "str"
},
Expand All @@ -23123,12 +23128,30 @@
"Whatever.",
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
],
"env": [
{
"name": "ANSIBLE_FOO"
},
{
"name": "ANSIBLE_BAR",
"version_added": "2.2.0"
},
{
"deprecated": {
"alternatives": "use C(ANSIBLE_BAR)",
"removed_from_collection": "ns2.col",
"version": "4.0.0",
"why": "Will be gone."
},
"name": "ANSIBLE_BAZ"
}
],
"required": true,
"type": "str"
}
},
"type": "dict",
"version_added": "2.0.0",
"version_added": "2.1.0",
"version_added_collection": "ns2.col"
}
},
Expand Down
25 changes: 24 additions & 1 deletion tests/functional/ansible-doc-cache-all.json
Original file line number Diff line number Diff line change
Expand Up @@ -23030,6 +23030,11 @@
},
"foo": {
"description": "The foo source.",
"env": [
{
"name": "ANSIBLE_FOO"
}
],
"required": true,
"type": "str"
},
Expand All @@ -23042,12 +23047,30 @@
"Whatever.",
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
],
"env": [
{
"name": "ANSIBLE_FOO"
},
{
"name": "ANSIBLE_BAR",
"version_added": "2.2.0"
},
{
"deprecated": {
"alternatives": "use C(ANSIBLE_BAR)",
"removed_from_collection": "ns2.col",
"version": "4.0.0",
"why": "Will be gone."
},
"name": "ANSIBLE_BAZ"
}
],
"required": true,
"type": "str"
}
},
"type": "dict",
"version_added": "2.0.0",
"version_added": "2.1.0",
"version_added_collection": "ns2.col"
}
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23030,6 +23030,11 @@
},
"foo": {
"description": "The foo source.",
"env": [
{
"name": "ANSIBLE_FOO"
}
],
"required": true,
"type": "str"
},
Expand All @@ -23042,12 +23047,30 @@
"Whatever.",
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
],
"env": [
{
"name": "ANSIBLE_FOO"
},
{
"name": "ANSIBLE_BAR",
"version_added": "2.2.0"
},
{
"deprecated": {
"alternatives": "use C(ANSIBLE_BAR)",
"removed_from_collection": "ns2.col",
"version": "4.0.0",
"why": "Will be gone."
},
"name": "ANSIBLE_BAZ"
}
],
"required": true,
"type": "str"
}
},
"type": "dict",
"version_added": "2.0.0",
"version_added": "2.1.0",
"version_added_collection": "ns2.col"
}
},
Expand Down
25 changes: 24 additions & 1 deletion tests/functional/ansible-doc-cache-ansible.builtin-ns2.col.json
Original file line number Diff line number Diff line change
Expand Up @@ -22655,6 +22655,11 @@
},
"foo": {
"description": "The foo source.",
"env": [
{
"name": "ANSIBLE_FOO"
}
],
"required": true,
"type": "str"
},
Expand All @@ -22667,12 +22672,30 @@
"Whatever.",
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
],
"env": [
{
"name": "ANSIBLE_FOO"
},
{
"name": "ANSIBLE_BAR",
"version_added": "2.2.0"
},
{
"deprecated": {
"alternatives": "use C(ANSIBLE_BAR)",
"removed_from_collection": "ns2.col",
"version": "4.0.0",
"why": "Will be gone."
},
"name": "ANSIBLE_BAZ"
}
],
"required": true,
"type": "str"
}
},
"type": "dict",
"version_added": "2.0.0",
"version_added": "2.1.0",
"version_added_collection": "ns2.col"
}
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1497,6 +1497,11 @@
},
"foo": {
"description": "The foo source.",
"env": [
{
"name": "ANSIBLE_FOO"
}
],
"required": true,
"type": "str"
},
Expand All @@ -1509,12 +1514,30 @@
"Whatever.",
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
],
"env": [
{
"name": "ANSIBLE_FOO"
},
{
"name": "ANSIBLE_BAR",
"version_added": "2.2.0"
},
{
"deprecated": {
"alternatives": "use C(ANSIBLE_BAR)",
"removed_from_collection": "ns2.col",
"version": "4.0.0",
"why": "Will be gone."
},
"name": "ANSIBLE_BAZ"
}
],
"required": true,
"type": "str"
}
},
"type": "dict",
"version_added": "2.0.0",
"version_added": "2.1.0",
"version_added_collection": "ns2.col"
}
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1122,6 +1122,11 @@
},
"foo": {
"description": "The foo source.",
"env": [
{
"name": "ANSIBLE_FOO"
}
],
"required": true,
"type": "str"
},
Expand All @@ -1134,12 +1139,30 @@
"Whatever.",
"Also required when O(subfoo) is specified when O(foo=bar) or V(baz)."
],
"env": [
{
"name": "ANSIBLE_FOO"
},
{
"name": "ANSIBLE_BAR",
"version_added": "2.2.0"
},
{
"deprecated": {
"alternatives": "use C(ANSIBLE_BAR)",
"removed_from_collection": "ns2.col",
"version": "4.0.0",
"why": "Will be gone."
},
"name": "ANSIBLE_BAZ"
}
],
"required": true,
"type": "str"
}
},
"type": "dict",
"version_added": "2.0.0",
"version_added": "2.1.0",
"version_added_collection": "ns2.col"
}
},
Expand Down
Loading

0 comments on commit 883482c

Please sign in to comment.