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 Apr 8, 2023
1 parent fdc47d4 commit e581253
Show file tree
Hide file tree
Showing 24 changed files with 382 additions and 24 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 @@ -11,7 +11,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
21 changes: 13 additions & 8 deletions src/antsibull_docs/data/docsite/macros/parameters.rst.j2
Original file line number Diff line number Diff line change
Expand Up @@ -99,12 +99,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 @@ -132,23 +136,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 @@ -228,8 +232,9 @@
<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>
{% 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"><span class="ansible-option-configuration">Configuration:</span></p>
<p>The below environment variable{% if value['env'] | length > 1 %}s{% endif %} will be used on the host that executes this module.</p>
<ul class="simple">
{% if value['ini'] %}
<li>
Expand Down Expand Up @@ -257,7 +262,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 @@ -266,7 +271,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 @@ -275,7 +280,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
4 changes: 3 additions & 1 deletion src/antsibull_docs/schemas/docs/module.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,11 @@
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: t.List[OptionEnvSchema] = []
suboptions: t.Dict[str, 'InnerModuleOptionsSchema'] = {}

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


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


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 @@ -1334,6 +1334,11 @@
},
"foo": {
"description": "The foo source.",
"env": [
{
"name": "ANSIBLE_FOO"
}
],
"required": true,
"type": "str"
},
Expand All @@ -1346,12 +1351,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-ns2.col.json
Original file line number Diff line number Diff line change
Expand Up @@ -1099,6 +1099,11 @@
},
"foo": {
"description": "The foo source.",
"env": [
{
"name": "ANSIBLE_FOO"
}
],
"required": true,
"type": "str"
},
Expand All @@ -1111,12 +1116,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
2 changes: 1 addition & 1 deletion tests/functional/ansible-version.output
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
ansible [core 2.15.0b1.post0] (stable-2.15 8f0ddcba2c) last updated 2023/04/06 20:47:29 (GMT +200)
ansible [core 2.16.0.dev0] (devel 88a380c8f0) last updated 2023/04/06 20:47:05 (GMT +200)
config file = None
configured module search path = ['<<<<<HOME>>>>>/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
ansible python module location = <<<<<ANSIBLE>>>>>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,35 @@
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`.

.. envvar:: ANSIBLE_BAR

A sub foo.

Whatever.

Also required when \ :ansopt:`subfoo`\ is specified when \ :ansopt:`foo=bar`\ or \ :ansval:`baz`\ .

*Used by:*
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
.. envvar:: ANSIBLE_BAZ

A sub foo.

Whatever.

Also required when \ :ansopt:`subfoo`\ is specified when \ :ansopt:`foo=bar`\ or \ :ansval:`baz`\ .

*Used by:*
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
.. envvar:: ANSIBLE_FOO

See the documentations for the options where this environment variable is used.

*Used by:*
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
.. envvar:: ANSIBLE_FOO_EXE

Foo executable.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,15 @@ Parameters
The foo source.


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

:ansible-option-configuration:`Configuration:`

The below environment variable will be used on the host that executes this module.

- Environment variable: :envvar:`ANSIBLE\_FOO`


.. raw:: html

</div>
Expand All @@ -203,7 +212,7 @@ Parameters

:ansible-option-type:`dictionary`

:ansible-option-versionadded:`added in ns2.col 2.0.0`
:ansible-option-versionadded:`added in ns2.col 2.1.0`


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


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

:ansible-option-configuration:`Configuration:`

The below environment variables will be used on the host that executes this module.

- Environment variable: :envvar:`ANSIBLE\_FOO`

- Environment variable: :envvar:`ANSIBLE\_BAR`

:ansible-option-versionadded:`added in ns2.col 2.2.0`

- Environment variable: :envvar:`ANSIBLE\_BAZ`

Removed in: version 4.0.0

Why: Will be gone.

Alternative: use \ :literal:`ANSIBLE\_BAR`\



.. raw:: html

</div>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,35 @@
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`.

.. envvar:: ANSIBLE_BAR

A sub foo.

Whatever.

Also required when \ :ansopt:`subfoo`\ is specified when \ :ansopt:`foo=bar`\ or \ :ansval:`baz`\ .

*Used by:*
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
.. envvar:: ANSIBLE_BAZ

A sub foo.

Whatever.

Also required when \ :ansopt:`subfoo`\ is specified when \ :ansopt:`foo=bar`\ or \ :ansval:`baz`\ .

*Used by:*
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
.. envvar:: ANSIBLE_FOO

See the documentations for the options where this environment variable is used.

*Used by:*
:ref:`ns2.col.foo module <ansible_collections.ns2.col.foo_module>`
.. envvar:: ANSIBLE_FOO_EXE

Foo executable.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,15 @@ Parameters
The foo source.


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

:ansible-option-configuration:`Configuration:`

The below environment variable will be used on the host that executes this module.

- Environment variable: :envvar:`ANSIBLE\_FOO`


.. raw:: html

</div>
Expand All @@ -203,7 +212,7 @@ Parameters

:ansible-option-type:`dictionary`

:ansible-option-versionadded:`added in ns2.col 2.0.0`
:ansible-option-versionadded:`added in ns2.col 2.1.0`


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


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

:ansible-option-configuration:`Configuration:`

The below environment variables will be used on the host that executes this module.

- Environment variable: :envvar:`ANSIBLE\_FOO`

- Environment variable: :envvar:`ANSIBLE\_BAR`

:ansible-option-versionadded:`added in ns2.col 2.2.0`

- Environment variable: :envvar:`ANSIBLE\_BAZ`

Removed in: version 4.0.0

Why: Will be gone.

Alternative: use \ :literal:`ANSIBLE\_BAR`\



.. raw:: html

</div>
Expand Down
Loading

0 comments on commit e581253

Please sign in to comment.