-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Improve environment variable handling. Create an environment variable…
… index.
- Loading branch information
1 parent
5e7d1b5
commit b301d0f
Showing
31 changed files
with
479 additions
and
48 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| minor_changes: | ||
| - "Use correct markup (``envvar`` role) for environment variables. Compile an index of all environment variables used by plugins (https://github.com/ansible-community/antsibull-docs/pull/73)." |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
39 changes: 39 additions & 0 deletions
39
src/antsibull_docs/data/docsite/list_of_env_variables.rst.j2
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| {# | ||
| Copyright (c) Ansible Project | ||
| GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) | ||
| SPDX-License-Identifier: GPL-3.0-or-later | ||
| #} | ||
|
|
||
| :orphan: | ||
|
|
||
| .. _list_of_collection_env_vars: | ||
|
|
||
| Index of all Collection Environment Variables | ||
| ============================================= | ||
|
|
||
| The following index documents all environment variables declared by plugins in collections. | ||
| Environment variables used by the ansible-core configuation are documented in :ref:`ansible_configuration_settings`. | ||
| {# TODO: use label `ansible_configuration_env_vars` once the ansible-core PR is merged #} | ||
|
|
||
| {% for _, env_var in env_variables | dictsort %} | ||
| .. envvar:: @{ env_var.name }@ | ||
|
|
||
| {% for paragraph in env_var.description or [] %} | ||
| @{ paragraph | replace('\n', '\n ') | rst_ify | indent(4) }@ | ||
|
|
||
| {% endfor %} | ||
| *Used by:* | ||
| {% set plugins_ = [] %} | ||
| {% for plugin_type, plugins in env_var.plugins.items() %} | ||
| {% for plugin_name in plugins %} | ||
| {% set _ = plugins_.append((plugin_name, plugin_type)) %} | ||
| {% endfor %} | ||
| {% endfor %} | ||
| {% for plugin_name, plugin_type in plugins_ | unique | sort %} | ||
| :ref:`@{ plugin_name | rst_escape }@ {% if plugin_type == 'module' %}module{% else %}@{ plugin_type }@ plugin{% endif %} <ansible_collections.@{ plugin_name }@_@{ plugin_type }@>` | ||
| {%- if not loop.last -%} | ||
| , | ||
| {% endif -%} | ||
| {%- endfor %} | ||
|
|
||
| {% endfor %} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,124 @@ | ||
| # Author: Felix Fontein <felix@fontein.de> | ||
| # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or | ||
| # https://www.gnu.org/licenses/gpl-3.0.txt) | ||
| # SPDX-License-Identifier: GPL-3.0-or-later | ||
| # SPDX-FileCopyrightText: 2022, Ansible Project | ||
| """Environment variable handling.""" | ||
|
|
||
| import os | ||
| import os.path | ||
| import typing as t | ||
|
|
||
| from antsibull_core import yaml | ||
|
|
||
| from .docs_parsing import AnsibleCollectionMetadata | ||
|
|
||
|
|
||
| class EnvironmentVariableInfo: | ||
| name: str | ||
| description: t.Optional[t.List[str]] | ||
| plugins: t.Dict[str, t.List[str]] # maps plugin_type to lists of plugin FQCNs | ||
|
|
||
| def __init__(self, | ||
| name: str, | ||
| description: t.Optional[t.List[str]] = None, | ||
| plugins: t.Optional[t.Dict[str, t.List[str]]] = None): | ||
| self.name = name | ||
| self.description = description | ||
| self.plugins = plugins or {} | ||
|
|
||
| def __repr__(self): | ||
| return f'E({self.name}, description={repr(self.description)}, plugins={self.plugins})' | ||
|
|
||
|
|
||
| def load_ansible_config(ansible_builtin_metadata: AnsibleCollectionMetadata | ||
| ) -> t.Mapping[str, t.Mapping[str, t.Any]]: | ||
| """ | ||
| Load Ansible base configuration (``lib/ansible/config/base.yml``). | ||
| :arg ansible_builtin_metadata: Metadata for the ansible.builtin collection. | ||
| :returns: A Mapping of configuration options to information on these options. | ||
| """ | ||
| return yaml.load_yaml_file(os.path.join(ansible_builtin_metadata.path, 'config', 'base.yml')) | ||
|
|
||
|
|
||
| def _find_env_vars(options: t.Mapping[str, t.Mapping[str, t.Any]] | ||
| ) -> t.Generator[t.Tuple[str, t.Optional[t.List[str]]], None, None]: | ||
| for _, option_data in options.items(): | ||
| if isinstance(option_data.get('env'), list): | ||
| description = option_data.get('description') | ||
| if isinstance(description, str): | ||
| description = [description] | ||
| if isinstance(description, list): | ||
| description = [str(desc) for desc in description] | ||
| else: | ||
| description = None | ||
| for env_var in option_data['env']: | ||
| if isinstance(env_var.get('name'), str): | ||
| yield (env_var['name'], description) | ||
| if isinstance(option_data.get('suboptions'), dict): | ||
| yield from _find_env_vars(option_data['suboptions']) | ||
|
|
||
|
|
||
| def _collect_env_vars_and_descriptions(plugin_info: t.Mapping[str, t.Mapping[str, t.Any]], | ||
| core_envs: t.Set[str], | ||
| ) -> t.Tuple[t.Mapping[str, EnvironmentVariableInfo], | ||
| t.Mapping[str, t.List[t.List[str]]]]: | ||
| other_variables: t.Dict[str, EnvironmentVariableInfo] = {} | ||
| other_variable_description: t.Dict[str, t.List[t.List[str]]] = {} | ||
| for plugin_type, plugins in plugin_info.items(): | ||
| for plugin_name, plugin_data in plugins.items(): | ||
| plugin_options: t.Mapping[str, t.Mapping[str, t.Any]] = ( | ||
| (plugin_data.get('doc') or {}).get('options') or {} | ||
| ) | ||
| for env_var, env_var_description in _find_env_vars(plugin_options): | ||
| if env_var in core_envs: | ||
| continue | ||
| if env_var not in other_variables: | ||
| other_variables[env_var] = EnvironmentVariableInfo(env_var) | ||
| other_variable_description[env_var] = [] | ||
| if plugin_type not in other_variables[env_var].plugins: | ||
| other_variables[env_var].plugins[plugin_type] = [] | ||
| other_variables[env_var].plugins[plugin_type].append(plugin_name) | ||
| if env_var_description is not None: | ||
| other_variable_description[env_var].append(env_var_description) | ||
| return other_variables, other_variable_description | ||
|
|
||
|
|
||
| def _augment_env_var_descriptions(other_variables: t.Mapping[str, EnvironmentVariableInfo], | ||
| other_variable_description: t.Mapping[str, t.List[t.List[str]]], | ||
| ) -> None: | ||
| for variable, variable_info in other_variables.items(): | ||
| if other_variable_description[variable]: | ||
| value: t.Optional[t.List[str]] = other_variable_description[variable][0] | ||
| for other_value in other_variable_description[variable]: | ||
| if value != other_value: | ||
| value = [ | ||
| 'See the documentations for the options where this environment variable' | ||
| ' is used.' | ||
| ] | ||
| break | ||
| variable_info.description = value | ||
|
|
||
|
|
||
| def collect_referenced_environment_variables(plugin_info: t.Mapping[str, t.Mapping[str, t.Any]], | ||
| ansible_config: t.Mapping[str, t.Mapping[str, t.Any]], | ||
| ) -> t.Mapping[str, EnvironmentVariableInfo]: | ||
| """ | ||
| Collect referenced environment variables that are not defined in the ansible-core | ||
| configuration. | ||
| :arg plugin_info: Mapping of plugin type to a mapping of plugin name to plugin record. | ||
| :arg ansible_config: The Ansible base configuration (``lib/ansible/config/base.yml``). | ||
| :returns: A Mapping of environment variable name to an environment variable infomation object. | ||
| """ | ||
| core_envs = {'ANSIBLE_CONFIG'} | ||
| for config in ansible_config.values(): | ||
| if config.get('env'): | ||
| for env in config['env']: | ||
| core_envs.add(env['name']) | ||
|
|
||
| other_variables, other_variable_description = _collect_env_vars_and_descriptions( | ||
| plugin_info, core_envs) | ||
| _augment_env_var_descriptions(other_variables, other_variable_description) | ||
| return other_variables |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
41 changes: 41 additions & 0 deletions
41
tests/functional/baseline-default/collections/environment_variables.rst
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
|
|
||
| :orphan: | ||
|
|
||
| .. _list_of_collection_env_vars: | ||
|
|
||
| Index of all Collection Environment Variables | ||
| ============================================= | ||
|
|
||
| The following index documents all environment variables declared by plugins in collections. | ||
| Environment variables used by the ansible-core configuation are documented in :ref:`ansible_configuration_settings`. | ||
|
|
||
| .. envvar:: ANSIBLE_FOO_EXE | ||
|
|
||
| Foo executable. | ||
|
|
||
| *Used by:* | ||
| :ref:`ns2.col.foo become plugin <ansible_collections.ns2.col.foo_become>` | ||
| .. envvar:: ANSIBLE_FOO_FILENAME_EXT | ||
|
|
||
| All extensions to check. | ||
|
|
||
| *Used by:* | ||
| :ref:`ns2.col.foo vars plugin <ansible_collections.ns2.col.foo_vars>` | ||
| .. envvar:: ANSIBLE_FOO_USER | ||
|
|
||
| User you 'become' to execute the task. | ||
|
|
||
| *Used by:* | ||
| :ref:`ns2.col.foo become plugin <ansible_collections.ns2.col.foo_become>` | ||
| .. envvar:: ANSIBLE_REMOTE_TEMP | ||
|
|
||
| Temporary directory to use on targets when executing tasks. | ||
|
|
||
| *Used by:* | ||
| :ref:`ns2.col.foo shell plugin <ansible_collections.ns2.col.foo_shell>` | ||
| .. envvar:: ANSIBLE_REMOTE_TMP | ||
|
|
||
| Temporary directory to use on targets when executing tasks. | ||
|
|
||
| *Used by:* | ||
| :ref:`ns2.col.foo shell plugin <ansible_collections.ns2.col.foo_shell>` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.