From 4a2e5f7f20471c8637f00bc12eac0812d979d8f4 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 26 Nov 2022 16:53:03 +0100 Subject: [PATCH] Improve environment variable handling. Create an environment variable index. --- changelogs/fragments/73-env-vars.yml | 2 + src/antsibull_docs/cli/doc_commands/stable.py | 25 +++- .../data/docsite/list_of_env_variables.rst.j2 | 39 ++++++ .../data/docsite/macros/parameters.rst.j2 | 4 +- src/antsibull_docs/env_variables.py | 124 ++++++++++++++++++ src/antsibull_docs/write_docs.py | 48 ++++++- .../collections/environment_variables.rst | 41 ++++++ .../collections/ns2/col/foo_become.rst | 8 +- .../collections/ns2/col/foo_cache.rst | 2 +- .../collections/ns2/col/foo_shell.rst | 4 +- .../collections/ns2/col/foo_vars.rst | 2 +- .../collections/environment_variables.rst | 41 ++++++ .../collections/ns2/col/foo_become.rst | 8 +- .../collections/ns2/col/foo_cache.rst | 2 +- .../collections/ns2/col/foo_shell.rst | 4 +- .../collections/ns2/col/foo_vars.rst | 2 +- .../collections/environment_variables.rst | 41 ++++++ .../collections/ns2/col/foo_become.rst | 8 +- .../collections/ns2/col/foo_cache.rst | 2 +- .../collections/ns2/col/foo_shell.rst | 4 +- .../collections/ns2/col/foo_vars.rst | 2 +- .../environment_variables.rst | 41 ++++++ .../baseline-squash-hierarchy/foo_become.rst | 8 +- .../baseline-squash-hierarchy/foo_cache.rst | 2 +- .../baseline-squash-hierarchy/foo_shell.rst | 4 +- .../baseline-squash-hierarchy/foo_vars.rst | 2 +- .../collections/environment_variables.rst | 41 ++++++ .../collections/ns2/col/foo_become.rst | 8 +- .../collections/ns2/col/foo_cache.rst | 2 +- .../collections/ns2/col/foo_shell.rst | 4 +- .../collections/ns2/col/foo_vars.rst | 2 +- 31 files changed, 479 insertions(+), 48 deletions(-) create mode 100644 changelogs/fragments/73-env-vars.yml create mode 100644 src/antsibull_docs/data/docsite/list_of_env_variables.rst.j2 create mode 100644 src/antsibull_docs/env_variables.py create mode 100644 tests/functional/baseline-default/collections/environment_variables.rst create mode 100644 tests/functional/baseline-no-breadcrumbs/collections/environment_variables.rst create mode 100644 tests/functional/baseline-no-indexes/collections/environment_variables.rst create mode 100644 tests/functional/baseline-squash-hierarchy/environment_variables.rst create mode 100644 tests/functional/baseline-use-html-blobs/collections/environment_variables.rst diff --git a/changelogs/fragments/73-env-vars.yml b/changelogs/fragments/73-env-vars.yml new file mode 100644 index 00000000..0d6b941a --- /dev/null +++ b/changelogs/fragments/73-env-vars.yml @@ -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)." diff --git a/src/antsibull_docs/cli/doc_commands/stable.py b/src/antsibull_docs/cli/doc_commands/stable.py index 58eab144..317b208d 100644 --- a/src/antsibull_docs/cli/doc_commands/stable.py +++ b/src/antsibull_docs/cli/doc_commands/stable.py @@ -37,6 +37,7 @@ load_all_collection_routing, remove_redirect_duplicates, ) +from ...env_variables import load_ansible_config, collect_referenced_environment_variables from ...schemas.docs import DOCS_SCHEMAS from ...utils.collection_name_transformer import CollectionNameTransformer from ...write_docs import ( @@ -47,6 +48,7 @@ output_indexes, output_plugin_indexes, output_extra_docs, + output_environment_variables, ) if t.TYPE_CHECKING: @@ -337,12 +339,16 @@ def generate_docs_for_all_collections(venv: t.Union[VenvRunner, FakeVenvRunner], app_ctx = app_context.app_ctx.get() # Get the info from the plugins - plugin_info, collection_metadata = asyncio_run(get_ansible_plugin_info( + plugin_info, full_collection_metadata = asyncio_run(get_ansible_plugin_info( venv, collection_dir, collection_names=collection_names)) flog.notice('Finished parsing info from plugins and collections') # flog.fields(plugin_info=plugin_info).debug('Plugin data') # flog.fields( - # collection_metadata=collection_metadata).debug('Collection metadata') + # collection_metadata=full_collection_metadata).debug('Collection metadata') + + collection_metadata = dict(full_collection_metadata) + if collection_names is not None and 'ansible.builtin' not in collection_names: + del collection_metadata['ansible.builtin'] # Load collection routing information collection_routing = asyncio_run(load_all_collection_routing(collection_metadata)) @@ -363,7 +369,7 @@ def generate_docs_for_all_collections(venv: t.Union[VenvRunner, FakeVenvRunner], {name: data.path for name, data in collection_metadata.items()})) flog.debug('Finished getting collection extra docs data') - # Load collection extra docs data + # Load collection links data link_data = asyncio_run(load_collections_links( {name: data.path for name, data in collection_metadata.items()})) flog.debug('Finished getting collection link data') @@ -384,6 +390,10 @@ def generate_docs_for_all_collections(venv: t.Union[VenvRunner, FakeVenvRunner], print(f"{plugin_name} {plugin_type}: {textwrap.indent(error, ' ').lstrip()}") return 1 + # Handle environment variables + ansible_config = load_ansible_config(full_collection_metadata['ansible.builtin']) + referenced_env_vars = collect_referenced_environment_variables(new_plugin_info, ansible_config) + collection_namespaces = get_collection_namespaces(collection_to_plugin_info.keys()) collection_url = CollectionNameTransformer( @@ -444,7 +454,14 @@ def generate_docs_for_all_collections(venv: t.Union[VenvRunner, FakeVenvRunner], asyncio_run(output_extra_docs(dest_dir, extra_docs_data, squash_hierarchy=squash_hierarchy)) - flog.debug('Finished writing extra extra docs docs') + flog.debug('Finished writing extra docs') + + if referenced_env_vars: + asyncio_run(output_environment_variables(dest_dir, referenced_env_vars, + squash_hierarchy=squash_hierarchy)) + flog.debug('Finished writing environment variables') + else: + flog.debug('Skipping environment variables (as there are none)') return 0 diff --git a/src/antsibull_docs/data/docsite/list_of_env_variables.rst.j2 b/src/antsibull_docs/data/docsite/list_of_env_variables.rst.j2 new file mode 100644 index 00000000..9b8a4372 --- /dev/null +++ b/src/antsibull_docs/data/docsite/list_of_env_variables.rst.j2 @@ -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 %} ` +{%- if not loop.last -%} +, +{% endif -%} +{%- endfor %} + +{% endfor %} diff --git a/src/antsibull_docs/data/docsite/macros/parameters.rst.j2 b/src/antsibull_docs/data/docsite/macros/parameters.rst.j2 index 7e5ae650..07d05f18 100644 --- a/src/antsibull_docs/data/docsite/macros/parameters.rst.j2 +++ b/src/antsibull_docs/data/docsite/macros/parameters.rst.j2 @@ -125,7 +125,7 @@ {% endfor %} {% endif %} {% for env in value['env'] %} - - Environment variable: @{ env['name'] | rst_escape }@ + - Environment variable: :envvar:`@{ env['name'] | rst_escape(escape_ending_whitespace=true) }@` {% if env['version_added'] is still_relevant(collection=env['version_added_collection'] or collection) %} :ansible-option-versionadded:`added in @{ version_added_rst(env['version_added'], env['version_added_collection'] or collection) }@` @@ -250,7 +250,7 @@ {% endif %} {% for env in value['env'] %}
  • -

    Environment variable: @{ env['name'] | escape }@

    +

    Environment variable: @{ env['name'] | escape }@

    {% if env['version_added'] is still_relevant(collection=env['version_added_collection'] or collection) %}

    added in @{ version_added_html(env['version_added'], env['version_added_collection'] or collection) }@

    {% endif %} diff --git a/src/antsibull_docs/env_variables.py b/src/antsibull_docs/env_variables.py new file mode 100644 index 00000000..a10a1bcd --- /dev/null +++ b/src/antsibull_docs/env_variables.py @@ -0,0 +1,124 @@ +# Author: Felix Fontein +# 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 diff --git a/src/antsibull_docs/write_docs.py b/src/antsibull_docs/write_docs.py index 884b98d7..0c74ed39 100644 --- a/src/antsibull_docs/write_docs.py +++ b/src/antsibull_docs/write_docs.py @@ -21,8 +21,9 @@ from .jinja2.environment import doc_environment from .collection_links import CollectionLinks -from .extra_docs import CollectionExtraDocsInfoT from .docs_parsing import AnsibleCollectionMetadata +from .env_variables import EnvironmentVariableInfo +from .extra_docs import CollectionExtraDocsInfoT from .utils.collection_name_transformer import CollectionNameTransformer @@ -907,7 +908,7 @@ async def output_extra_docs(dest_dir: str, extra_docs_data: t.Mapping[str, CollectionExtraDocsInfoT], squash_hierarchy: bool = False) -> None: """ - Generate collection-level index pages for the collections. + Write extra docs pages for the collections. :arg dest_dir: The directory to place the documentation in. :arg extra_docs_data: Dictionary mapping collection names to CollectionExtraDocsInfoT. @@ -940,3 +941,46 @@ async def output_extra_docs(dest_dir: str, await asyncio.gather(*writers) flog.debug('Leave') + + +async def output_environment_variables(dest_dir: str, + env_variables: t.Mapping[str, EnvironmentVariableInfo], + squash_hierarchy: bool = False + ) -> None: + """ + Write environment variable Generate collection-level index pages for the collections. + + :arg dest_dir: The directory to place the documentation in. + :arg env_variables: Mapping of environment variable names to environment variable information. + :arg squash_hierarchy: If set to ``True``, no directory hierarchy will be used. + Undefined behavior if documentation for multiple collections are + created. + """ + flog = mlog.fields(func='write_environment_variables') + flog.debug('Enter') + + if not squash_hierarchy: + collection_toplevel = os.path.join(dest_dir, 'collections') + else: + collection_toplevel = dest_dir + + env = doc_environment(('antsibull_docs.data', 'docsite')) + # Get the templates + env_var_list_tmpl = env.get_template('list_of_env_variables.rst.j2') + + flog.fields(toplevel=collection_toplevel, exists=os.path.isdir(collection_toplevel)).debug( + 'collection_toplevel exists?') + # This is only safe because we made sure that the top of the directory tree we're writing to + # (docs/docsite/rst) is only writable by us. + os.makedirs(collection_toplevel, mode=0o755, exist_ok=True) + + index_file = os.path.join(collection_toplevel, 'environment_variables.rst') + index_contents = _render_template( + env_var_list_tmpl, + index_file, + env_variables=env_variables, + ) + + await write_file(index_file, index_contents) + + flog.debug('Leave') diff --git a/tests/functional/baseline-default/collections/environment_variables.rst b/tests/functional/baseline-default/collections/environment_variables.rst new file mode 100644 index 00000000..35269599 --- /dev/null +++ b/tests/functional/baseline-default/collections/environment_variables.rst @@ -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 ` +.. envvar:: ANSIBLE_FOO_FILENAME_EXT + + All extensions to check. + + *Used by:* + :ref:`ns2.col.foo vars plugin ` +.. envvar:: ANSIBLE_FOO_USER + + User you 'become' to execute the task. + + *Used by:* + :ref:`ns2.col.foo become plugin ` +.. envvar:: ANSIBLE_REMOTE_TEMP + + Temporary directory to use on targets when executing tasks. + + *Used by:* + :ref:`ns2.col.foo shell plugin ` +.. envvar:: ANSIBLE_REMOTE_TMP + + Temporary directory to use on targets when executing tasks. + + *Used by:* + :ref:`ns2.col.foo shell plugin ` diff --git a/tests/functional/baseline-default/collections/ns2/col/foo_become.rst b/tests/functional/baseline-default/collections/ns2/col/foo_become.rst index a3a6f56e..a72f549a 100644 --- a/tests/functional/baseline-default/collections/ns2/col/foo_become.rst +++ b/tests/functional/baseline-default/collections/ns2/col/foo_become.rst @@ -211,9 +211,9 @@ Parameters Alternative: nothing - - Environment variable: ANSIBLE\_BECOME\_EXE + - Environment variable: :envvar:`ANSIBLE\_BECOME\_EXE` - - Environment variable: ANSIBLE\_FOO\_EXE + - Environment variable: :envvar:`ANSIBLE\_FOO\_EXE` Removed in: version 3.0.0 @@ -297,11 +297,11 @@ Parameters user = root - - Environment variable: ANSIBLE\_BECOME\_USER + - Environment variable: :envvar:`ANSIBLE\_BECOME\_USER` :ansible-option-versionadded:`added in ns2.col 0.1.0` - - Environment variable: ANSIBLE\_FOO\_USER + - Environment variable: :envvar:`ANSIBLE\_FOO\_USER` - Variable: ansible\_become\_user diff --git a/tests/functional/baseline-default/collections/ns2/col/foo_cache.rst b/tests/functional/baseline-default/collections/ns2/col/foo_cache.rst index 57266438..219ae0f6 100644 --- a/tests/functional/baseline-default/collections/ns2/col/foo_cache.rst +++ b/tests/functional/baseline-default/collections/ns2/col/foo_cache.rst @@ -141,7 +141,7 @@ Parameters fact_caching_connection = VALUE - - Environment variable: ANSIBLE\_CACHE\_PLUGIN\_CONNECTION + - Environment variable: :envvar:`ANSIBLE\_CACHE\_PLUGIN\_CONNECTION` .. raw:: html diff --git a/tests/functional/baseline-default/collections/ns2/col/foo_shell.rst b/tests/functional/baseline-default/collections/ns2/col/foo_shell.rst index dad11b11..8ed400f9 100644 --- a/tests/functional/baseline-default/collections/ns2/col/foo_shell.rst +++ b/tests/functional/baseline-default/collections/ns2/col/foo_shell.rst @@ -148,9 +148,9 @@ Parameters remote_tmp = ~/.ansible/tmp - - Environment variable: ANSIBLE\_REMOTE\_TEMP + - Environment variable: :envvar:`ANSIBLE\_REMOTE\_TEMP` - - Environment variable: ANSIBLE\_REMOTE\_TMP + - Environment variable: :envvar:`ANSIBLE\_REMOTE\_TMP` - Variable: ansible\_remote\_tmp diff --git a/tests/functional/baseline-default/collections/ns2/col/foo_vars.rst b/tests/functional/baseline-default/collections/ns2/col/foo_vars.rst index 827aaf72..0df3babc 100644 --- a/tests/functional/baseline-default/collections/ns2/col/foo_vars.rst +++ b/tests/functional/baseline-default/collections/ns2/col/foo_vars.rst @@ -156,7 +156,7 @@ Parameters foo_valid_extensions = .foo, .foobar - - Environment variable: ANSIBLE\_FOO\_FILENAME\_EXT + - Environment variable: :envvar:`ANSIBLE\_FOO\_FILENAME\_EXT` .. raw:: html diff --git a/tests/functional/baseline-no-breadcrumbs/collections/environment_variables.rst b/tests/functional/baseline-no-breadcrumbs/collections/environment_variables.rst new file mode 100644 index 00000000..35269599 --- /dev/null +++ b/tests/functional/baseline-no-breadcrumbs/collections/environment_variables.rst @@ -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 ` +.. envvar:: ANSIBLE_FOO_FILENAME_EXT + + All extensions to check. + + *Used by:* + :ref:`ns2.col.foo vars plugin ` +.. envvar:: ANSIBLE_FOO_USER + + User you 'become' to execute the task. + + *Used by:* + :ref:`ns2.col.foo become plugin ` +.. envvar:: ANSIBLE_REMOTE_TEMP + + Temporary directory to use on targets when executing tasks. + + *Used by:* + :ref:`ns2.col.foo shell plugin ` +.. envvar:: ANSIBLE_REMOTE_TMP + + Temporary directory to use on targets when executing tasks. + + *Used by:* + :ref:`ns2.col.foo shell plugin ` diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_become.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_become.rst index a3a6f56e..a72f549a 100644 --- a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_become.rst +++ b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_become.rst @@ -211,9 +211,9 @@ Parameters Alternative: nothing - - Environment variable: ANSIBLE\_BECOME\_EXE + - Environment variable: :envvar:`ANSIBLE\_BECOME\_EXE` - - Environment variable: ANSIBLE\_FOO\_EXE + - Environment variable: :envvar:`ANSIBLE\_FOO\_EXE` Removed in: version 3.0.0 @@ -297,11 +297,11 @@ Parameters user = root - - Environment variable: ANSIBLE\_BECOME\_USER + - Environment variable: :envvar:`ANSIBLE\_BECOME\_USER` :ansible-option-versionadded:`added in ns2.col 0.1.0` - - Environment variable: ANSIBLE\_FOO\_USER + - Environment variable: :envvar:`ANSIBLE\_FOO\_USER` - Variable: ansible\_become\_user diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_cache.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_cache.rst index 57266438..219ae0f6 100644 --- a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_cache.rst +++ b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_cache.rst @@ -141,7 +141,7 @@ Parameters fact_caching_connection = VALUE - - Environment variable: ANSIBLE\_CACHE\_PLUGIN\_CONNECTION + - Environment variable: :envvar:`ANSIBLE\_CACHE\_PLUGIN\_CONNECTION` .. raw:: html diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_shell.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_shell.rst index dad11b11..8ed400f9 100644 --- a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_shell.rst +++ b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_shell.rst @@ -148,9 +148,9 @@ Parameters remote_tmp = ~/.ansible/tmp - - Environment variable: ANSIBLE\_REMOTE\_TEMP + - Environment variable: :envvar:`ANSIBLE\_REMOTE\_TEMP` - - Environment variable: ANSIBLE\_REMOTE\_TMP + - Environment variable: :envvar:`ANSIBLE\_REMOTE\_TMP` - Variable: ansible\_remote\_tmp diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_vars.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_vars.rst index 827aaf72..0df3babc 100644 --- a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_vars.rst +++ b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_vars.rst @@ -156,7 +156,7 @@ Parameters foo_valid_extensions = .foo, .foobar - - Environment variable: ANSIBLE\_FOO\_FILENAME\_EXT + - Environment variable: :envvar:`ANSIBLE\_FOO\_FILENAME\_EXT` .. raw:: html diff --git a/tests/functional/baseline-no-indexes/collections/environment_variables.rst b/tests/functional/baseline-no-indexes/collections/environment_variables.rst new file mode 100644 index 00000000..35269599 --- /dev/null +++ b/tests/functional/baseline-no-indexes/collections/environment_variables.rst @@ -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 ` +.. envvar:: ANSIBLE_FOO_FILENAME_EXT + + All extensions to check. + + *Used by:* + :ref:`ns2.col.foo vars plugin ` +.. envvar:: ANSIBLE_FOO_USER + + User you 'become' to execute the task. + + *Used by:* + :ref:`ns2.col.foo become plugin ` +.. envvar:: ANSIBLE_REMOTE_TEMP + + Temporary directory to use on targets when executing tasks. + + *Used by:* + :ref:`ns2.col.foo shell plugin ` +.. envvar:: ANSIBLE_REMOTE_TMP + + Temporary directory to use on targets when executing tasks. + + *Used by:* + :ref:`ns2.col.foo shell plugin ` diff --git a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_become.rst b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_become.rst index a3a6f56e..a72f549a 100644 --- a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_become.rst +++ b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_become.rst @@ -211,9 +211,9 @@ Parameters Alternative: nothing - - Environment variable: ANSIBLE\_BECOME\_EXE + - Environment variable: :envvar:`ANSIBLE\_BECOME\_EXE` - - Environment variable: ANSIBLE\_FOO\_EXE + - Environment variable: :envvar:`ANSIBLE\_FOO\_EXE` Removed in: version 3.0.0 @@ -297,11 +297,11 @@ Parameters user = root - - Environment variable: ANSIBLE\_BECOME\_USER + - Environment variable: :envvar:`ANSIBLE\_BECOME\_USER` :ansible-option-versionadded:`added in ns2.col 0.1.0` - - Environment variable: ANSIBLE\_FOO\_USER + - Environment variable: :envvar:`ANSIBLE\_FOO\_USER` - Variable: ansible\_become\_user diff --git a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_cache.rst b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_cache.rst index 57266438..219ae0f6 100644 --- a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_cache.rst +++ b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_cache.rst @@ -141,7 +141,7 @@ Parameters fact_caching_connection = VALUE - - Environment variable: ANSIBLE\_CACHE\_PLUGIN\_CONNECTION + - Environment variable: :envvar:`ANSIBLE\_CACHE\_PLUGIN\_CONNECTION` .. raw:: html diff --git a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_shell.rst b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_shell.rst index dad11b11..8ed400f9 100644 --- a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_shell.rst +++ b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_shell.rst @@ -148,9 +148,9 @@ Parameters remote_tmp = ~/.ansible/tmp - - Environment variable: ANSIBLE\_REMOTE\_TEMP + - Environment variable: :envvar:`ANSIBLE\_REMOTE\_TEMP` - - Environment variable: ANSIBLE\_REMOTE\_TMP + - Environment variable: :envvar:`ANSIBLE\_REMOTE\_TMP` - Variable: ansible\_remote\_tmp diff --git a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_vars.rst b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_vars.rst index 827aaf72..0df3babc 100644 --- a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_vars.rst +++ b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_vars.rst @@ -156,7 +156,7 @@ Parameters foo_valid_extensions = .foo, .foobar - - Environment variable: ANSIBLE\_FOO\_FILENAME\_EXT + - Environment variable: :envvar:`ANSIBLE\_FOO\_FILENAME\_EXT` .. raw:: html diff --git a/tests/functional/baseline-squash-hierarchy/environment_variables.rst b/tests/functional/baseline-squash-hierarchy/environment_variables.rst new file mode 100644 index 00000000..35269599 --- /dev/null +++ b/tests/functional/baseline-squash-hierarchy/environment_variables.rst @@ -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 ` +.. envvar:: ANSIBLE_FOO_FILENAME_EXT + + All extensions to check. + + *Used by:* + :ref:`ns2.col.foo vars plugin ` +.. envvar:: ANSIBLE_FOO_USER + + User you 'become' to execute the task. + + *Used by:* + :ref:`ns2.col.foo become plugin ` +.. envvar:: ANSIBLE_REMOTE_TEMP + + Temporary directory to use on targets when executing tasks. + + *Used by:* + :ref:`ns2.col.foo shell plugin ` +.. envvar:: ANSIBLE_REMOTE_TMP + + Temporary directory to use on targets when executing tasks. + + *Used by:* + :ref:`ns2.col.foo shell plugin ` diff --git a/tests/functional/baseline-squash-hierarchy/foo_become.rst b/tests/functional/baseline-squash-hierarchy/foo_become.rst index a3a6f56e..a72f549a 100644 --- a/tests/functional/baseline-squash-hierarchy/foo_become.rst +++ b/tests/functional/baseline-squash-hierarchy/foo_become.rst @@ -211,9 +211,9 @@ Parameters Alternative: nothing - - Environment variable: ANSIBLE\_BECOME\_EXE + - Environment variable: :envvar:`ANSIBLE\_BECOME\_EXE` - - Environment variable: ANSIBLE\_FOO\_EXE + - Environment variable: :envvar:`ANSIBLE\_FOO\_EXE` Removed in: version 3.0.0 @@ -297,11 +297,11 @@ Parameters user = root - - Environment variable: ANSIBLE\_BECOME\_USER + - Environment variable: :envvar:`ANSIBLE\_BECOME\_USER` :ansible-option-versionadded:`added in ns2.col 0.1.0` - - Environment variable: ANSIBLE\_FOO\_USER + - Environment variable: :envvar:`ANSIBLE\_FOO\_USER` - Variable: ansible\_become\_user diff --git a/tests/functional/baseline-squash-hierarchy/foo_cache.rst b/tests/functional/baseline-squash-hierarchy/foo_cache.rst index 57266438..219ae0f6 100644 --- a/tests/functional/baseline-squash-hierarchy/foo_cache.rst +++ b/tests/functional/baseline-squash-hierarchy/foo_cache.rst @@ -141,7 +141,7 @@ Parameters fact_caching_connection = VALUE - - Environment variable: ANSIBLE\_CACHE\_PLUGIN\_CONNECTION + - Environment variable: :envvar:`ANSIBLE\_CACHE\_PLUGIN\_CONNECTION` .. raw:: html diff --git a/tests/functional/baseline-squash-hierarchy/foo_shell.rst b/tests/functional/baseline-squash-hierarchy/foo_shell.rst index dad11b11..8ed400f9 100644 --- a/tests/functional/baseline-squash-hierarchy/foo_shell.rst +++ b/tests/functional/baseline-squash-hierarchy/foo_shell.rst @@ -148,9 +148,9 @@ Parameters remote_tmp = ~/.ansible/tmp - - Environment variable: ANSIBLE\_REMOTE\_TEMP + - Environment variable: :envvar:`ANSIBLE\_REMOTE\_TEMP` - - Environment variable: ANSIBLE\_REMOTE\_TMP + - Environment variable: :envvar:`ANSIBLE\_REMOTE\_TMP` - Variable: ansible\_remote\_tmp diff --git a/tests/functional/baseline-squash-hierarchy/foo_vars.rst b/tests/functional/baseline-squash-hierarchy/foo_vars.rst index 827aaf72..0df3babc 100644 --- a/tests/functional/baseline-squash-hierarchy/foo_vars.rst +++ b/tests/functional/baseline-squash-hierarchy/foo_vars.rst @@ -156,7 +156,7 @@ Parameters foo_valid_extensions = .foo, .foobar - - Environment variable: ANSIBLE\_FOO\_FILENAME\_EXT + - Environment variable: :envvar:`ANSIBLE\_FOO\_FILENAME\_EXT` .. raw:: html diff --git a/tests/functional/baseline-use-html-blobs/collections/environment_variables.rst b/tests/functional/baseline-use-html-blobs/collections/environment_variables.rst new file mode 100644 index 00000000..35269599 --- /dev/null +++ b/tests/functional/baseline-use-html-blobs/collections/environment_variables.rst @@ -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 ` +.. envvar:: ANSIBLE_FOO_FILENAME_EXT + + All extensions to check. + + *Used by:* + :ref:`ns2.col.foo vars plugin ` +.. envvar:: ANSIBLE_FOO_USER + + User you 'become' to execute the task. + + *Used by:* + :ref:`ns2.col.foo become plugin ` +.. envvar:: ANSIBLE_REMOTE_TEMP + + Temporary directory to use on targets when executing tasks. + + *Used by:* + :ref:`ns2.col.foo shell plugin ` +.. envvar:: ANSIBLE_REMOTE_TMP + + Temporary directory to use on targets when executing tasks. + + *Used by:* + :ref:`ns2.col.foo shell plugin ` diff --git a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_become.rst b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_become.rst index 9c9150e7..9758235c 100644 --- a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_become.rst +++ b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_become.rst @@ -143,11 +143,11 @@ Parameters
  • -

    Environment variable: ANSIBLE_BECOME_EXE

    +

    Environment variable: ANSIBLE_BECOME_EXE

  • -

    Environment variable: ANSIBLE_FOO_EXE

    +

    Environment variable: ANSIBLE_FOO_EXE

    Removed in: version 3.0.0

    Why: Just some text.

    Alternative: nothing

    @@ -197,12 +197,12 @@ Parameters
  • -

    Environment variable: ANSIBLE_BECOME_USER

    +

    Environment variable: ANSIBLE_BECOME_USER

    added in ns2.col 0.1.0

  • -

    Environment variable: ANSIBLE_FOO_USER

    +

    Environment variable: ANSIBLE_FOO_USER

  • diff --git a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_cache.rst b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_cache.rst index f04cc3ec..14d28d6b 100644 --- a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_cache.rst +++ b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_cache.rst @@ -118,7 +118,7 @@ Parameters
  • -

    Environment variable: ANSIBLE_CACHE_PLUGIN_CONNECTION

    +

    Environment variable: ANSIBLE_CACHE_PLUGIN_CONNECTION

    • diff --git a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_shell.rst b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_shell.rst index 696a1c3f..e582806e 100644 --- a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_shell.rst +++ b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_shell.rst @@ -119,11 +119,11 @@ Parameters
  • -

    Environment variable: ANSIBLE_REMOTE_TEMP

    +

    Environment variable: ANSIBLE_REMOTE_TEMP

  • -

    Environment variable: ANSIBLE_REMOTE_TMP

    +

    Environment variable: ANSIBLE_REMOTE_TMP

  • diff --git a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_vars.rst b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_vars.rst index 0cab47d2..080ce90c 100644 --- a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_vars.rst +++ b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_vars.rst @@ -130,7 +130,7 @@ Parameters
  • -

    Environment variable: ANSIBLE_FOO_FILENAME_EXT

    +

    Environment variable: ANSIBLE_FOO_FILENAME_EXT