diff --git a/changelogs/fragments/166-envvars.yml b/changelogs/fragments/166-envvars.yml new file mode 100644 index 00000000..4cd327be --- /dev/null +++ b/changelogs/fragments/166-envvars.yml @@ -0,0 +1,9 @@ +minor_changes: + - "Add the roles ``:ansenvvar:`` and ``:ansenvvarref:`` to the antsibull-docs Sphinx extension + (https://github.com/ansible-community/antsibull-docs/pull/166)." + - "Add the new collection config field ``envvar_directives`` which allows to declare which environment variables are + declared with an ``.. envvar::`` directive in the collection's extra docsite documentation. This is used, next to + the plugin configuration information and the ansible-core configuration information, to determine whether an environment + variable is referencable or not (https://github.com/ansible-community/antsibull-docs/pull/166)." + - "Render ``E(...)`` markup with ``:ansenvvarref:`` or ``:ansenvvar:`` depending on whether the environment variable + is known to be referencable or not (https://github.com/ansible-community/antsibull-docs/pull/166)." diff --git a/src/antsibull_docs/cli/doc_commands/_build.py b/src/antsibull_docs/cli/doc_commands/_build.py index 2380b327..42fea724 100644 --- a/src/antsibull_docs/cli/doc_commands/_build.py +++ b/src/antsibull_docs/cli/doc_commands/_build.py @@ -23,6 +23,7 @@ remove_redirect_duplicates, ) from ...env_variables import ( + collect_referable_envvars, collect_referenced_environment_variables, load_ansible_config, ) @@ -160,9 +161,12 @@ def generate_docs_for_all_collections( # Handle environment variables ansible_config = load_ansible_config(full_collection_metadata["ansible.builtin"]) - referenced_env_vars = collect_referenced_environment_variables( + referenced_env_vars, core_env_vars = collect_referenced_environment_variables( new_plugin_info, ansible_config ) + referable_envvars = collect_referable_envvars( + referenced_env_vars, core_env_vars, collection_metadata + ) collection_namespaces = get_collection_namespaces(collection_to_plugin_info.keys()) @@ -185,6 +189,7 @@ def generate_docs_for_all_collections( collection_install=collection_install, breadcrumbs=breadcrumbs, for_official_docsite=for_official_docsite, + referable_envvars=referable_envvars, ) ) flog.notice("Finished writing collection index") @@ -196,6 +201,7 @@ def generate_docs_for_all_collections( collection_install=collection_install, breadcrumbs=breadcrumbs, for_official_docsite=for_official_docsite, + referable_envvars=referable_envvars, ) ) flog.notice("Finished writing collection namespace index") @@ -207,6 +213,7 @@ def generate_docs_for_all_collections( collection_url=collection_url, collection_install=collection_install, for_official_docsite=for_official_docsite, + referable_envvars=referable_envvars, ) ) flog.notice("Finished writing plugin indexes") @@ -217,6 +224,7 @@ def generate_docs_for_all_collections( collection_url=collection_url, collection_install=collection_install, for_official_docsite=for_official_docsite, + referable_envvars=referable_envvars, ) ) flog.notice("Finished writing callback plugin indexes") @@ -233,6 +241,7 @@ def generate_docs_for_all_collections( link_data=link_data, breadcrumbs=breadcrumbs, for_official_docsite=for_official_docsite, + referable_envvars=referable_envvars, ) ) flog.notice("Finished writing indexes") @@ -247,6 +256,7 @@ def generate_docs_for_all_collections( link_data=link_data, squash_hierarchy=squash_hierarchy, for_official_docsite=for_official_docsite, + referable_envvars=referable_envvars, ) ) flog.debug("Finished writing plugin stubs") @@ -264,6 +274,7 @@ def generate_docs_for_all_collections( squash_hierarchy=squash_hierarchy, use_html_blobs=use_html_blobs, for_official_docsite=for_official_docsite, + referable_envvars=referable_envvars, ) ) flog.debug("Finished writing plugin docs") @@ -275,7 +286,10 @@ def generate_docs_for_all_collections( asyncio.run( output_environment_variables( - dest_dir, referenced_env_vars, squash_hierarchy=squash_hierarchy + dest_dir, + referenced_env_vars, + squash_hierarchy=squash_hierarchy, + referable_envvars=referable_envvars, ) ) flog.debug("Finished writing environment variables") diff --git a/src/antsibull_docs/env_variables.py b/src/antsibull_docs/env_variables.py index 0dcee973..15cfab07 100644 --- a/src/antsibull_docs/env_variables.py +++ b/src/antsibull_docs/env_variables.py @@ -114,14 +114,17 @@ def _augment_env_var_descriptions( def collect_referenced_environment_variables( plugin_info: Mapping[str, Mapping[str, t.Any]], ansible_config: Mapping[str, Mapping[str, t.Any]], -) -> Mapping[str, EnvironmentVariableInfo]: +) -> tuple[Mapping[str, EnvironmentVariableInfo], set[str]]: """ 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. + :returns: A tuple consisting of a + Mapping of environment variable name to an environment variable infomation object, + and a set of environment variable names that are part of the ansible-core + configuration. """ core_envs = {"ANSIBLE_CONFIG"} for config in ansible_config.values(): @@ -133,4 +136,26 @@ def collect_referenced_environment_variables( plugin_info, core_envs ) _augment_env_var_descriptions(other_variables, other_variable_description) - return other_variables + return other_variables, core_envs + + +def collect_referable_envvars( + referenced_env_vars: Mapping[str, EnvironmentVariableInfo], + core_env_vars: set[str], + collection_metadata: Mapping[str, AnsibleCollectionMetadata], +) -> set[str]: + """ + :arg referenced_env_vars: A Mapping of environment variable name to an + environment variable infomation object. + :arg core_env_vars: Set of environment variable names that are part of the + ansible-core configuration. + :arg collection_metadata: A Mapping of collection names to collection metadata + objects. + :returns: A set of environment variables that can be referenced via the + ``:envvar:`` role. + """ + referable_envvars = set(referenced_env_vars) + referable_envvars.update(core_env_vars) + for collection_meta in collection_metadata.values(): + referable_envvars.update(collection_meta.docs_config.envvar_directives) + return referable_envvars diff --git a/src/antsibull_docs/jinja2/environment.py b/src/antsibull_docs/jinja2/environment.py index b2f8914f..fc735588 100644 --- a/src/antsibull_docs/jinja2/environment.py +++ b/src/antsibull_docs/jinja2/environment.py @@ -60,6 +60,7 @@ def doc_environment( extra_tests: Mapping[str, t.Callable] | None = None, collection_url: CollectionNameTransformer | None = None, collection_install: CollectionNameTransformer | None = None, + referable_envvars: set[str] | None = None, ) -> Environment: loader: BaseLoader if isinstance(template_location, str) and os.path.exists(template_location): @@ -86,7 +87,6 @@ def doc_environment( # with str: """Write value as :code:`...` RST construct.""" if not isinstance(value, str): value = str(value) - return f":code:`{rst_escape(value, escape_ending_whitespace=True)}`" + return f":code:`{_rst_escape(value, escape_ending_whitespace=True)}`" + + +class CustomizedAntsibullRSTFormatter(AntsibullRSTFormatter): + def __init__(self, referable_envvars: set[str] | None = None): + self._referable_envvars = referable_envvars or set() + + def format_env_variable(self, part: dom.EnvVariablePart) -> str: + envvar = part.name.split("=", 1)[0].strip() + if envvar in self._referable_envvars: + return f"\\ :ansenvvarref:`{_rst_escape(part.name, True)}`\\ " + return f"\\ :ansenvvar:`{_rst_escape(part.name, True)}`\\ " def rst_ify( @@ -40,6 +52,7 @@ def rst_ify( plugin_fqcn: str | None = None, plugin_type: str | None = None, role_entrypoint: str | None = None, + referable_envvars: set[str] | None = None, ) -> tuple[str, Mapping[str, int]]: """convert symbols like I(this is in italics) to valid restructured text""" current_plugin: dom.PluginIdentifier | None = None @@ -47,6 +60,10 @@ def rst_ify( current_plugin = dom.PluginIdentifier(fqcn=plugin_fqcn, type=plugin_type) context = Context(current_plugin=current_plugin, role_entrypoint=role_entrypoint) paragraphs = parse(text, context, errors="message") - text = to_rst(paragraphs, current_plugin=current_plugin) + text = to_rst( + paragraphs, + current_plugin=current_plugin, + formatter=CustomizedAntsibullRSTFormatter(referable_envvars), + ) counts = _count(paragraphs) return text, counts diff --git a/src/antsibull_docs/schemas/collection_config.py b/src/antsibull_docs/schemas/collection_config.py index a65af3d7..4f368e46 100644 --- a/src/antsibull_docs/schemas/collection_config.py +++ b/src/antsibull_docs/schemas/collection_config.py @@ -13,4 +13,10 @@ class CollectionConfig(p.BaseModel): + # Whether the collection uses flatmapping to flatten subdirectories in + # `plugins/*/`. flatmap: bool = False + + # List of environment variables that are defined by `.. envvar::` directives + # in the extra docsite RST files. + envvar_directives: list[str] = [] diff --git a/src/antsibull_docs/write_docs/collections.py b/src/antsibull_docs/write_docs/collections.py index 096e532d..043a60d3 100644 --- a/src/antsibull_docs/write_docs/collections.py +++ b/src/antsibull_docs/write_docs/collections.py @@ -137,6 +137,7 @@ async def output_indexes( squash_hierarchy: bool = False, breadcrumbs: bool = True, for_official_docsite: bool = False, + referable_envvars: set[str] | None = None, ) -> None: """ Generate collection-level index pages for the collections. @@ -153,6 +154,7 @@ async def output_indexes( disabled. This will disable breadcrumbs but save on memory usage. :kwarg for_official_docsite: Default False. Set to True to use wording specific for the official docsite on docs.ansible.com. + :kwarg referable_envvars: Optional set of environment variables that can be referenced. """ flog = mlog.fields(func="output_indexes") flog.debug("Enter") @@ -164,6 +166,7 @@ async def output_indexes( ("antsibull_docs.data", "docsite"), collection_url=collection_url, collection_install=collection_install, + referable_envvars=referable_envvars, ) # Get the templates collection_plugins_tmpl = env.get_template("plugins_by_collection.rst.j2") diff --git a/src/antsibull_docs/write_docs/hierarchy.py b/src/antsibull_docs/write_docs/hierarchy.py index 08a9813c..10ec477c 100644 --- a/src/antsibull_docs/write_docs/hierarchy.py +++ b/src/antsibull_docs/write_docs/hierarchy.py @@ -103,6 +103,7 @@ async def output_collection_index( collection_install: CollectionNameTransformer, breadcrumbs: bool = True, for_official_docsite: bool = False, + referable_envvars: set[str] | None = None, ) -> None: """ Generate top-level collection index page for the collections. @@ -115,6 +116,7 @@ async def output_collection_index( disabled. This will disable breadcrumbs but save on memory usage. :kwarg for_official_docsite: Default False. Set to True to use wording specific for the official docsite on docs.ansible.com. + :kwarg referable_envvars: Optional set of environment variables that can be referenced. """ flog = mlog.fields(func="output_collection_index") flog.debug("Enter") @@ -123,6 +125,7 @@ async def output_collection_index( ("antsibull_docs.data", "docsite"), collection_url=collection_url, collection_install=collection_install, + referable_envvars=referable_envvars, ) # Get the templates collection_list_tmpl = env.get_template("list_of_collections.rst.j2") @@ -154,6 +157,7 @@ async def output_collection_namespace_indexes( collection_install: CollectionNameTransformer, breadcrumbs: bool = True, for_official_docsite: bool = False, + referable_envvars: set[str] | None = None, ) -> None: """ Generate collection namespace index pages for the collections. @@ -164,6 +168,7 @@ async def output_collection_namespace_indexes( disabled. This will disable breadcrumbs but save on memory usage. :kwarg for_official_docsite: Default False. Set to True to use wording specific for the official docsite on docs.ansible.com. + :kwarg referable_envvars: Optional set of environment variables that can be referenced. """ flog = mlog.fields(func="output_collection_namespace_indexes") flog.debug("Enter") @@ -172,6 +177,7 @@ async def output_collection_namespace_indexes( ("antsibull_docs.data", "docsite"), collection_url=collection_url, collection_install=collection_install, + referable_envvars=referable_envvars, ) # Get the templates collection_list_tmpl = env.get_template("list_of_collections_by_namespace.rst.j2") diff --git a/src/antsibull_docs/write_docs/indexes.py b/src/antsibull_docs/write_docs/indexes.py index 4ed93382..8093eb52 100644 --- a/src/antsibull_docs/write_docs/indexes.py +++ b/src/antsibull_docs/write_docs/indexes.py @@ -94,6 +94,7 @@ async def output_callback_indexes( collection_url: CollectionNameTransformer, collection_install: CollectionNameTransformer, for_official_docsite: bool = False, + referable_envvars: set[str] | None = None, ) -> None: """ Generate top-level callback plugin index pages for all callback plugins of a type in all @@ -104,6 +105,7 @@ async def output_callback_indexes( :arg dest_dir: The directory to place the documentation in. :kwarg for_official_docsite: Default False. Set to True to use wording specific for the official docsite on docs.ansible.com. + :kwarg referable_envvars: Optional set of environment variables that can be referenced. """ flog = mlog.fields(func="output_callback_indexes") flog.debug("Enter") @@ -112,6 +114,7 @@ async def output_callback_indexes( ("antsibull_docs.data", "docsite"), collection_url=collection_url, collection_install=collection_install, + referable_envvars=referable_envvars, ) # Get the templates plugin_list_tmpl = env.get_template("list_of_callback_plugins.rst.j2") @@ -155,6 +158,7 @@ async def output_plugin_indexes( collection_url: CollectionNameTransformer, collection_install: CollectionNameTransformer, for_official_docsite: bool = False, + referable_envvars: set[str] | None = None, ) -> None: """ Generate top-level plugin index pages for all plugins of a type in all collections. @@ -165,6 +169,7 @@ async def output_plugin_indexes( :arg dest_dir: The directory to place the documentation in. :kwarg for_official_docsite: Default False. Set to True to use wording specific for the official docsite on docs.ansible.com. + :kwarg referable_envvars: Optional set of environment variables that can be referenced. """ flog = mlog.fields(func="output_plugin_indexes") flog.debug("Enter") @@ -173,6 +178,7 @@ async def output_plugin_indexes( ("antsibull_docs.data", "docsite"), collection_url=collection_url, collection_install=collection_install, + referable_envvars=referable_envvars, ) # Get the templates plugin_list_tmpl = env.get_template("list_of_plugins.rst.j2") @@ -212,6 +218,7 @@ async def output_environment_variables( dest_dir: str, env_variables: Mapping[str, EnvironmentVariableInfo], squash_hierarchy: bool = False, + referable_envvars: set[str] | None = None, ) -> None: """ Write environment variable Generate collection-level index pages for the collections. @@ -221,6 +228,7 @@ async def output_environment_variables( :arg squash_hierarchy: If set to ``True``, no directory hierarchy will be used. Undefined behavior if documentation for multiple collections are created. + :kwarg referable_envvars: Optional set of environment variables that can be referenced. """ flog = mlog.fields(func="write_environment_variables") flog.debug("Enter") @@ -230,7 +238,10 @@ async def output_environment_variables( else: collection_toplevel = dest_dir - env = doc_environment(("antsibull_docs.data", "docsite")) + env = doc_environment( + ("antsibull_docs.data", "docsite"), + referable_envvars=referable_envvars, + ) # Get the templates env_var_list_tmpl = env.get_template("list_of_env_variables.rst.j2") diff --git a/src/antsibull_docs/write_docs/plugin_stubs.py b/src/antsibull_docs/write_docs/plugin_stubs.py index 42fc593c..6b735990 100644 --- a/src/antsibull_docs/write_docs/plugin_stubs.py +++ b/src/antsibull_docs/write_docs/plugin_stubs.py @@ -129,6 +129,7 @@ async def output_all_plugin_stub_rst( link_data: Mapping[str, CollectionLinks], squash_hierarchy: bool = False, for_official_docsite: bool = False, + referable_envvars: set[str] | None = None, ) -> None: """ Output rst files for each plugin stub. @@ -143,12 +144,14 @@ async def output_all_plugin_stub_rst( created. :kwarg for_official_docsite: Default False. Set to True to use wording specific for the official docsite on docs.ansible.com. + :kwarg referable_envvars: Optional set of environment variables that can be referenced. """ # Setup the jinja environment env = doc_environment( ("antsibull_docs.data", "docsite"), collection_url=collection_url, collection_install=collection_install, + referable_envvars=referable_envvars, ) # Get the templates redirect_tmpl = env.get_template("plugin-redirect.rst.j2") diff --git a/src/antsibull_docs/write_docs/plugins.py b/src/antsibull_docs/write_docs/plugins.py index 99218d90..1fe96085 100644 --- a/src/antsibull_docs/write_docs/plugins.py +++ b/src/antsibull_docs/write_docs/plugins.py @@ -342,6 +342,7 @@ async def output_all_plugin_rst( squash_hierarchy: bool = False, use_html_blobs: bool = False, for_official_docsite: bool = False, + referable_envvars: set[str] | None = None, ) -> None: """ Output rst files for each plugin. @@ -361,12 +362,14 @@ async def output_all_plugin_rst( tables instead of using RST tables. :kwarg for_official_docsite: Default False. Set to True to use wording specific for the official docsite on docs.ansible.com. + :kwarg referable_envvars: Optional set of environment variables that can be referenced. """ # Setup the jinja environment env = doc_environment( ("antsibull_docs.data", "docsite"), collection_url=collection_url, collection_install=collection_install, + referable_envvars=referable_envvars, ) # Get the templates plugin_tmpl = env.get_template("plugin.rst.j2") diff --git a/src/sphinx_antsibull_ext/roles.py b/src/sphinx_antsibull_ext/roles.py index be2f3bbb..eab2d154 100644 --- a/src/sphinx_antsibull_ext/roles.py +++ b/src/sphinx_antsibull_ext/roles.py @@ -254,6 +254,54 @@ def return_value_role(name, rawtext, text, lineno, inliner, options={}, content= return [nodes.literal(rawtext, text, *subnodes, classes=classes)], [] +# pylint:disable-next=unused-argument,dangerous-default-value +def environment_variable(name, rawtext, text, lineno, inliner, options={}, content=[]): + """Format environment variable with possible assignment, without reference. + + Returns 2 part tuple containing list of nodes to insert into the + document and a list of system messages. Both are allowed to be + empty. + + :param name: The role name used in the document. + :param rawtext: The entire markup snippet, with role. + :param text: The text marked with the role. + :param lineno: The line number where rawtext appears in the input. + :param inliner: The inliner instance that called us. + :param options: Directive options for customization. + :param content: The directive content for customization. + """ + classes = ["xref", "std", "std-envvar"] + return [nodes.literal(rawtext, text, classes=classes)], [] + + +# pylint:disable-next=dangerous-default-value +def environment_variable_reference( + name, # pylint:disable=unused-argument + rawtext, + text, + lineno, # pylint:disable=unused-argument + inliner, # pylint:disable=unused-argument + options={}, + content=[], +): + # Extract the name of the environment variable + ref = text.replace("\x00", "").split("=", 1)[0].strip() + + classes = ["xref", "std", "std-envvar"] + content = nodes.literal(rawtext, text, classes=classes) + + options = { + "reftype": "envvar", + "refdomain": "std", + "refexplicit": True, + "refwarn": True, + } + refnode = addnodes.pending_xref(text, content, **options) + refnode["reftarget"] = ref + + return [refnode], [] + + ROLES = { "ansible-option-choices-entry": option_choice, "ansible-option-choices-entry-default": option_choice_default, @@ -262,6 +310,8 @@ def return_value_role(name, rawtext, text, lineno, inliner, options={}, content= "ansopt": option_role, "ansval": value_role, "ansretval": return_value_role, + "ansenvvar": environment_variable, + "ansenvvarref": environment_variable_reference, } diff --git a/tests/functional/ansible-doc-cache-all-others.json b/tests/functional/ansible-doc-cache-all-others.json index b51eb141..df7c9386 100644 --- a/tests/functional/ansible-doc-cache-all-others.json +++ b/tests/functional/ansible-doc-cache-all-others.json @@ -1390,6 +1390,7 @@ "Secret used to either login the ssh server or as a passphrase for ssh keys that require it", "Can be set from the CLI via the C(--ask-pass) option." ], + "type": "string", "vars": [ { "name": "ansible_password" @@ -1487,6 +1488,7 @@ "version_added_collection": "ansible.builtin" } ], + "type": "string", "vars": [ { "name": "ansible_private_key_file" @@ -1518,6 +1520,7 @@ "section": "paramiko_connection" } ], + "type": "string", "vars": [ { "name": "ansible_paramiko_proxy_command", @@ -1563,6 +1566,7 @@ "description": [ "Address of the remote target" ], + "type": "string", "vars": [ { "name": "inventory_hostname" @@ -1610,6 +1614,7 @@ "name": "remote_user" } ], + "type": "string", "vars": [ { "name": "ansible_user" @@ -1642,6 +1647,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_args", @@ -1679,6 +1685,7 @@ "version_added_collection": "ansible.builtin" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_common_args" @@ -1714,6 +1721,7 @@ "version_added_collection": "ansible.builtin" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_extra_args" @@ -1987,7 +1995,7 @@ ] }, "ignore_proxy": { - "default": "no", + "default": false, "description": [ "Will disable any environment proxy settings and connect directly to the remote host.", "This option is ignored if C(proxy) is set." @@ -2341,6 +2349,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_control_path", @@ -2366,6 +2375,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_control_path_dir", @@ -2377,6 +2387,7 @@ "host": { "default": "inventory_hostname", "description": "Hostname/IP to connect to.", + "type": "string", "vars": [ { "name": "inventory_hostname" @@ -2436,6 +2447,7 @@ }, "password": { "description": "Authentication password for the C(remote_user). Can be supplied as CLI option.", + "type": "string", "vars": [ { "name": "ansible_password" @@ -2504,6 +2516,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_pkcs11_provider" @@ -2561,6 +2574,7 @@ "section": "defaults" } ], + "type": "string", "vars": [ { "name": "ansible_private_key_file" @@ -2627,6 +2641,7 @@ "name": "remote_user" } ], + "type": "string", "vars": [ { "name": "ansible_user" @@ -2652,6 +2667,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_scp_executable", @@ -2685,6 +2701,7 @@ "version_added_collection": "ansible.builtin" } ], + "type": "string", "vars": [ { "name": "ansible_scp_extra_args" @@ -2726,7 +2743,7 @@ ] }, "sftp_batch_mode": { - "default": "yes", + "default": true, "description": "TODO: write it", "env": [ { @@ -2764,6 +2781,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_sftp_executable", @@ -2797,6 +2815,7 @@ "version_added_collection": "ansible.builtin" } ], + "type": "string", "vars": [ { "name": "ansible_sftp_extra_args" @@ -2817,6 +2836,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_args", @@ -2848,6 +2868,7 @@ "version_added_collection": "ansible.builtin" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_common_args" @@ -2871,6 +2892,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_executable", @@ -2904,6 +2926,7 @@ "version_added_collection": "ansible.builtin" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_extra_args" @@ -2934,6 +2957,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_transfer_method", @@ -2959,6 +2983,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_sshpass_prompt" @@ -3010,7 +3035,7 @@ ] }, "use_tty": { - "default": "yes", + "default": true, "description": "add -tt to ssh commands to force tty allocation.", "env": [ { @@ -8257,12 +8282,14 @@ "description": "list of files to template" }, "comment_end_string": { + "default": "#}", "description": "The string marking the end of a comment statement.", "type": "str", "version_added": "2.12", "version_added_collection": "ansible.builtin" }, "comment_start_string": { + "default": "{#", "description": "The string marking the beginning of a comment statement.", "type": "str", "version_added": "2.12", @@ -9428,7 +9455,7 @@ "version_added": "1.0", "version_added_collection": "ansible.builtin" }, - "examples": "\n- name: One way to avoid apt_key once it is removed from your distro, armored keys should use .asc extension, binary should use .gpg\n block:\n - name: somerepo | no apt key\n ansible.builtin.get_url:\n url: https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x36a1d7869245c8950f966e92d8576a8ba88d21e9\n dest: /etc/apt/keyrings/myrepo.asc\n\n - name: somerepo | apt source\n ansible.builtin.apt_repository:\n repo: \"deb [arch=amd64 signed-by=/etc/apt/keyrings/myrepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable\"\n state: present\n\n- name: Add an apt key by id from a keyserver\n ansible.builtin.apt_key:\n keyserver: keyserver.ubuntu.com\n id: 36A1D7869245C8950F966E92D8576A8BA88D21E9\n\n- name: Add an Apt signing key, uses whichever key is at the URL\n ansible.builtin.apt_key:\n url: https://ftp-master.debian.org/keys/archive-key-6.0.asc\n state: present\n\n- name: Add an Apt signing key, will not download if present\n ansible.builtin.apt_key:\n id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n url: https://ftp-master.debian.org/keys/archive-key-6.0.asc\n state: present\n\n- name: Remove a Apt specific signing key, leading 0x is valid\n ansible.builtin.apt_key:\n id: 0x9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n state: absent\n\n# Use armored file since utf-8 string is expected. Must be of \"PGP PUBLIC KEY BLOCK\" type.\n- name: Add a key from a file on the Ansible server\n ansible.builtin.apt_key:\n data: \"{{ lookup('ansible.builtin.file', 'apt.asc') }}\"\n state: present\n\n- name: Add an Apt signing key to a specific keyring file\n ansible.builtin.apt_key:\n id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n url: https://ftp-master.debian.org/keys/archive-key-6.0.asc\n keyring: /etc/apt/trusted.gpg.d/debian.gpg\n\n- name: Add Apt signing key on remote server to keyring\n ansible.builtin.apt_key:\n id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n file: /tmp/apt.gpg\n state: present\n", + "examples": "\n- name: One way to avoid apt_key once it is removed from your distro, armored keys should use .asc extension, binary should use .gpg\n block:\n - name: somerepo | no apt key\n ansible.builtin.get_url:\n url: https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x36a1d7869245c8950f966e92d8576a8ba88d21e9\n dest: /etc/apt/keyrings/myrepo.asc\n checksum: sha256:bb42f0db45d46bab5f9ec619e1a47360b94c27142e57aa71f7050d08672309e0\n\n - name: somerepo | apt source\n ansible.builtin.apt_repository:\n repo: \"deb [arch=amd64 signed-by=/etc/apt/keyrings/myrepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable\"\n state: present\n\n- name: Add an apt key by id from a keyserver\n ansible.builtin.apt_key:\n keyserver: keyserver.ubuntu.com\n id: 36A1D7869245C8950F966E92D8576A8BA88D21E9\n\n- name: Add an Apt signing key, uses whichever key is at the URL\n ansible.builtin.apt_key:\n url: https://ftp-master.debian.org/keys/archive-key-6.0.asc\n state: present\n\n- name: Add an Apt signing key, will not download if present\n ansible.builtin.apt_key:\n id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n url: https://ftp-master.debian.org/keys/archive-key-6.0.asc\n state: present\n\n- name: Remove a Apt specific signing key, leading 0x is valid\n ansible.builtin.apt_key:\n id: 0x9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n state: absent\n\n# Use armored file since utf-8 string is expected. Must be of \"PGP PUBLIC KEY BLOCK\" type.\n- name: Add a key from a file on the Ansible server\n ansible.builtin.apt_key:\n data: \"{{ lookup('ansible.builtin.file', 'apt.asc') }}\"\n state: present\n\n- name: Add an Apt signing key to a specific keyring file\n ansible.builtin.apt_key:\n id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n url: https://ftp-master.debian.org/keys/archive-key-6.0.asc\n keyring: /etc/apt/trusted.gpg.d/debian.gpg\n\n- name: Add Apt signing key on remote server to keyring\n ansible.builtin.apt_key:\n id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n file: /tmp/apt.gpg\n state: present\n", "metadata": null, "return": { "after": { @@ -12938,6 +12965,7 @@ "contains": { "description": [ "A regular expression or pattern which should be matched against the file content.", + "If I(read_whole_file) is C(true) it matches against the beginning of the line (uses C(re.match())). If I(read_whole_file) is C(false), it searches anywhere for that pattern (uses C(re.search())).", "Works only when I(file_type) is C(file)." ], "type": "str" @@ -19278,7 +19306,7 @@ "WatchdogTimestampMonotonic": "0", "WatchdogUSec": "0" }, - "type": "complex" + "type": "dict" } } }, @@ -19394,27 +19422,35 @@ "metadata": null, "return": { "results": { - "description": "results from actions taken", - "returned": "always", - "sample": { - "attempts": 1, - "changed": true, - "name": "apache2", + "contains": { + "name": { + "description": "Name of the service", + "returned": "always", + "sample": "apache2", + "type": "str" + }, "status": { - "enabled": { - "changed": true, - "rc": 0, - "stderr": "", - "stdout": "" + "description": "Status of the service", + "returned": "changed", + "sample": { + "enabled": { + "changed": true, + "rc": 0, + "stderr": "", + "stdout": "" + }, + "stopped": { + "changed": true, + "rc": 0, + "stderr": "", + "stdout": "Stopping web server: apache2.\n" + } }, - "stopped": { - "changed": true, - "rc": 0, - "stderr": "", - "stdout": "Stopping web server: apache2.\n" - } + "type": "dict" } }, + "description": "results from actions taken", + "returned": "always", "type": "complex" } } @@ -22871,7 +22907,8 @@ "collection": "ns2.col", "description": [ "Does some foo on the remote host.", - "Whether foo is magic or not has not yet been determined." + "Whether foo is magic or not has not yet been determined.", + "E(FOOBAR1), E(FOOBAR2), E(FOOBAR3), E(FOOBAR4)." ], "filename": "ansible_collections/ns2/col/plugins/modules/foo.py", "has_action": false, @@ -23116,7 +23153,8 @@ "A sub foo.", "Whatever.", "Also required when O(subfoo) is specified when O(foo=bar) or V(baz).", - "Note that O(subfoo.foo) is the same as O(subbaz.foo), O(subbaz.bam), and O(subfoo.bam)." + "Note that O(subfoo.foo) is the same as O(subbaz.foo), O(subbaz.bam), and O(subfoo.bam).", + "E(FOOBAR1), E(FOOBAR2), E(FOOBAR3), E(FOOBAR4)." ], "required": true, "type": "str" diff --git a/tests/functional/ansible-doc-cache-all.json b/tests/functional/ansible-doc-cache-all.json index d153425f..fdbf9163 100644 --- a/tests/functional/ansible-doc-cache-all.json +++ b/tests/functional/ansible-doc-cache-all.json @@ -1390,6 +1390,7 @@ "Secret used to either login the ssh server or as a passphrase for ssh keys that require it", "Can be set from the CLI via the C(--ask-pass) option." ], + "type": "string", "vars": [ { "name": "ansible_password" @@ -1487,6 +1488,7 @@ "version_added_collection": "ansible.builtin" } ], + "type": "string", "vars": [ { "name": "ansible_private_key_file" @@ -1518,6 +1520,7 @@ "section": "paramiko_connection" } ], + "type": "string", "vars": [ { "name": "ansible_paramiko_proxy_command", @@ -1563,6 +1566,7 @@ "description": [ "Address of the remote target" ], + "type": "string", "vars": [ { "name": "inventory_hostname" @@ -1610,6 +1614,7 @@ "name": "remote_user" } ], + "type": "string", "vars": [ { "name": "ansible_user" @@ -1642,6 +1647,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_args", @@ -1679,6 +1685,7 @@ "version_added_collection": "ansible.builtin" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_common_args" @@ -1714,6 +1721,7 @@ "version_added_collection": "ansible.builtin" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_extra_args" @@ -1987,7 +1995,7 @@ ] }, "ignore_proxy": { - "default": "no", + "default": false, "description": [ "Will disable any environment proxy settings and connect directly to the remote host.", "This option is ignored if C(proxy) is set." @@ -2341,6 +2349,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_control_path", @@ -2366,6 +2375,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_control_path_dir", @@ -2377,6 +2387,7 @@ "host": { "default": "inventory_hostname", "description": "Hostname/IP to connect to.", + "type": "string", "vars": [ { "name": "inventory_hostname" @@ -2436,6 +2447,7 @@ }, "password": { "description": "Authentication password for the C(remote_user). Can be supplied as CLI option.", + "type": "string", "vars": [ { "name": "ansible_password" @@ -2504,6 +2516,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_pkcs11_provider" @@ -2561,6 +2574,7 @@ "section": "defaults" } ], + "type": "string", "vars": [ { "name": "ansible_private_key_file" @@ -2627,6 +2641,7 @@ "name": "remote_user" } ], + "type": "string", "vars": [ { "name": "ansible_user" @@ -2652,6 +2667,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_scp_executable", @@ -2685,6 +2701,7 @@ "version_added_collection": "ansible.builtin" } ], + "type": "string", "vars": [ { "name": "ansible_scp_extra_args" @@ -2726,7 +2743,7 @@ ] }, "sftp_batch_mode": { - "default": "yes", + "default": true, "description": "TODO: write it", "env": [ { @@ -2764,6 +2781,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_sftp_executable", @@ -2797,6 +2815,7 @@ "version_added_collection": "ansible.builtin" } ], + "type": "string", "vars": [ { "name": "ansible_sftp_extra_args" @@ -2817,6 +2836,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_args", @@ -2848,6 +2868,7 @@ "version_added_collection": "ansible.builtin" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_common_args" @@ -2871,6 +2892,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_executable", @@ -2904,6 +2926,7 @@ "version_added_collection": "ansible.builtin" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_extra_args" @@ -2934,6 +2957,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_ssh_transfer_method", @@ -2959,6 +2983,7 @@ "section": "ssh_connection" } ], + "type": "string", "vars": [ { "name": "ansible_sshpass_prompt" @@ -3010,7 +3035,7 @@ ] }, "use_tty": { - "default": "yes", + "default": true, "description": "add -tt to ssh commands to force tty allocation.", "env": [ { @@ -8257,12 +8282,14 @@ "description": "list of files to template" }, "comment_end_string": { + "default": "#}", "description": "The string marking the end of a comment statement.", "type": "str", "version_added": "2.12", "version_added_collection": "ansible.builtin" }, "comment_start_string": { + "default": "{#", "description": "The string marking the beginning of a comment statement.", "type": "str", "version_added": "2.12", @@ -9394,7 +9421,7 @@ "version_added": "1.0", "version_added_collection": "ansible.builtin" }, - "examples": "\n- name: One way to avoid apt_key once it is removed from your distro, armored keys should use .asc extension, binary should use .gpg\n block:\n - name: somerepo | no apt key\n ansible.builtin.get_url:\n url: https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x36a1d7869245c8950f966e92d8576a8ba88d21e9\n dest: /etc/apt/keyrings/myrepo.asc\n\n - name: somerepo | apt source\n ansible.builtin.apt_repository:\n repo: \"deb [arch=amd64 signed-by=/etc/apt/keyrings/myrepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable\"\n state: present\n\n- name: Add an apt key by id from a keyserver\n ansible.builtin.apt_key:\n keyserver: keyserver.ubuntu.com\n id: 36A1D7869245C8950F966E92D8576A8BA88D21E9\n\n- name: Add an Apt signing key, uses whichever key is at the URL\n ansible.builtin.apt_key:\n url: https://ftp-master.debian.org/keys/archive-key-6.0.asc\n state: present\n\n- name: Add an Apt signing key, will not download if present\n ansible.builtin.apt_key:\n id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n url: https://ftp-master.debian.org/keys/archive-key-6.0.asc\n state: present\n\n- name: Remove a Apt specific signing key, leading 0x is valid\n ansible.builtin.apt_key:\n id: 0x9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n state: absent\n\n# Use armored file since utf-8 string is expected. Must be of \"PGP PUBLIC KEY BLOCK\" type.\n- name: Add a key from a file on the Ansible server\n ansible.builtin.apt_key:\n data: \"{{ lookup('ansible.builtin.file', 'apt.asc') }}\"\n state: present\n\n- name: Add an Apt signing key to a specific keyring file\n ansible.builtin.apt_key:\n id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n url: https://ftp-master.debian.org/keys/archive-key-6.0.asc\n keyring: /etc/apt/trusted.gpg.d/debian.gpg\n\n- name: Add Apt signing key on remote server to keyring\n ansible.builtin.apt_key:\n id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n file: /tmp/apt.gpg\n state: present\n", + "examples": "\n- name: One way to avoid apt_key once it is removed from your distro, armored keys should use .asc extension, binary should use .gpg\n block:\n - name: somerepo | no apt key\n ansible.builtin.get_url:\n url: https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x36a1d7869245c8950f966e92d8576a8ba88d21e9\n dest: /etc/apt/keyrings/myrepo.asc\n checksum: sha256:bb42f0db45d46bab5f9ec619e1a47360b94c27142e57aa71f7050d08672309e0\n\n - name: somerepo | apt source\n ansible.builtin.apt_repository:\n repo: \"deb [arch=amd64 signed-by=/etc/apt/keyrings/myrepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable\"\n state: present\n\n- name: Add an apt key by id from a keyserver\n ansible.builtin.apt_key:\n keyserver: keyserver.ubuntu.com\n id: 36A1D7869245C8950F966E92D8576A8BA88D21E9\n\n- name: Add an Apt signing key, uses whichever key is at the URL\n ansible.builtin.apt_key:\n url: https://ftp-master.debian.org/keys/archive-key-6.0.asc\n state: present\n\n- name: Add an Apt signing key, will not download if present\n ansible.builtin.apt_key:\n id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n url: https://ftp-master.debian.org/keys/archive-key-6.0.asc\n state: present\n\n- name: Remove a Apt specific signing key, leading 0x is valid\n ansible.builtin.apt_key:\n id: 0x9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n state: absent\n\n# Use armored file since utf-8 string is expected. Must be of \"PGP PUBLIC KEY BLOCK\" type.\n- name: Add a key from a file on the Ansible server\n ansible.builtin.apt_key:\n data: \"{{ lookup('ansible.builtin.file', 'apt.asc') }}\"\n state: present\n\n- name: Add an Apt signing key to a specific keyring file\n ansible.builtin.apt_key:\n id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n url: https://ftp-master.debian.org/keys/archive-key-6.0.asc\n keyring: /etc/apt/trusted.gpg.d/debian.gpg\n\n- name: Add Apt signing key on remote server to keyring\n ansible.builtin.apt_key:\n id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA\n file: /tmp/apt.gpg\n state: present\n", "metadata": null, "return": { "after": { @@ -12904,6 +12931,7 @@ "contains": { "description": [ "A regular expression or pattern which should be matched against the file content.", + "If I(read_whole_file) is C(true) it matches against the beginning of the line (uses C(re.match())). If I(read_whole_file) is C(false), it searches anywhere for that pattern (uses C(re.search())).", "Works only when I(file_type) is C(file)." ], "type": "str" @@ -19244,7 +19272,7 @@ "WatchdogTimestampMonotonic": "0", "WatchdogUSec": "0" }, - "type": "complex" + "type": "dict" } } }, @@ -19360,27 +19388,35 @@ "metadata": null, "return": { "results": { - "description": "results from actions taken", - "returned": "always", - "sample": { - "attempts": 1, - "changed": true, - "name": "apache2", + "contains": { + "name": { + "description": "Name of the service", + "returned": "always", + "sample": "apache2", + "type": "str" + }, "status": { - "enabled": { - "changed": true, - "rc": 0, - "stderr": "", - "stdout": "" + "description": "Status of the service", + "returned": "changed", + "sample": { + "enabled": { + "changed": true, + "rc": 0, + "stderr": "", + "stdout": "" + }, + "stopped": { + "changed": true, + "rc": 0, + "stderr": "", + "stdout": "Stopping web server: apache2.\n" + } }, - "stopped": { - "changed": true, - "rc": 0, - "stderr": "", - "stdout": "Stopping web server: apache2.\n" - } + "type": "dict" } }, + "description": "results from actions taken", + "returned": "always", "type": "complex" } } @@ -22790,7 +22826,8 @@ "collection": "ns2.col", "description": [ "Does some foo on the remote host.", - "Whether foo is magic or not has not yet been determined." + "Whether foo is magic or not has not yet been determined.", + "E(FOOBAR1), E(FOOBAR2), E(FOOBAR3), E(FOOBAR4)." ], "filename": "ansible_collections/ns2/col/plugins/modules/foo.py", "has_action": false, @@ -23035,7 +23072,8 @@ "A sub foo.", "Whatever.", "Also required when O(subfoo) is specified when O(foo=bar) or V(baz).", - "Note that O(subfoo.foo) is the same as O(subbaz.foo), O(subbaz.bam), and O(subfoo.bam)." + "Note that O(subfoo.foo) is the same as O(subbaz.foo), O(subbaz.bam), and O(subfoo.bam).", + "E(FOOBAR1), E(FOOBAR2), E(FOOBAR3), E(FOOBAR4)." ], "required": true, "type": "str" diff --git a/tests/functional/ansible-doc-cache-ns2.col.json b/tests/functional/ansible-doc-cache-ns2.col.json index f506cff2..51c17aff 100644 --- a/tests/functional/ansible-doc-cache-ns2.col.json +++ b/tests/functional/ansible-doc-cache-ns2.col.json @@ -1101,7 +1101,8 @@ "collection": "ns2.col", "description": [ "Does some foo on the remote host.", - "Whether foo is magic or not has not yet been determined." + "Whether foo is magic or not has not yet been determined.", + "E(FOOBAR1), E(FOOBAR2), E(FOOBAR3), E(FOOBAR4)." ], "filename": "ansible_collections/ns2/col/plugins/modules/foo.py", "has_action": false, diff --git a/tests/functional/ansible-doc-cache-ns2.flatcol.json b/tests/functional/ansible-doc-cache-ns2.flatcol.json index 79ca1df6..14607666 100644 --- a/tests/functional/ansible-doc-cache-ns2.flatcol.json +++ b/tests/functional/ansible-doc-cache-ns2.flatcol.json @@ -690,7 +690,8 @@ "A sub foo.", "Whatever.", "Also required when O(subfoo) is specified when O(foo=bar) or V(baz).", - "Note that O(subfoo.foo) is the same as O(subbaz.foo), O(subbaz.bam), and O(subfoo.bam)." + "Note that O(subfoo.foo) is the same as O(subbaz.foo), O(subbaz.bam), and O(subfoo.bam).", + "E(FOOBAR1), E(FOOBAR2), E(FOOBAR3), E(FOOBAR4)." ], "required": true, "type": "str" diff --git a/tests/functional/ansible-version.output b/tests/functional/ansible-version.output index 627757d0..267f09eb 100644 --- a/tests/functional/ansible-version.output +++ b/tests/functional/ansible-version.output @@ -1,9 +1,9 @@ -ansible [core 2.16.0.dev0] (devel 6e137433ae) last updated 2023/06/08 12:34:49 (GMT +200) +ansible [core 2.16.0.dev0] (devel 73e04ef2d6) last updated 2023/06/13 23:00:13 (GMT +200) config file = None configured module search path = ['<<<<>>>>/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules'] ansible python module location = <<<<>>>> ansible collection location = <<<<>>>> executable location = <<<<>>>>/.local/bin/ansible - python version = 3.11.3 (main, Apr 5 2023, 15:52:25) [GCC 12.2.1 20230201] (/usr/bin/python) + python version = 3.11.3 (main, Jun 5 2023, 09:32:32) [GCC 13.1.1 20230429] (/usr/bin/python) jinja version = 3.1.2 libyaml = True diff --git a/tests/functional/baseline-default/collections/ns2/col/docsite/filter_guide.rst b/tests/functional/baseline-default/collections/ns2/col/docsite/filter_guide.rst index 02b1bf67..0354846d 100644 --- a/tests/functional/baseline-default/collections/ns2/col/docsite/filter_guide.rst +++ b/tests/functional/baseline-default/collections/ns2/col/docsite/filter_guide.rst @@ -16,3 +16,15 @@ The :ref:`ns2.col collection ` offers two filters. - ``ns2.col.foo``: foo! - ``ns2.col.bar``: bar! + +.. envvar:: FOOBAR1 + + This is one environment variable. + +.. envvar:: FOOBAR2 + + This is another environment variable. + +.. envvar:: FOOBAR3 + + This is a third environment variable. diff --git a/tests/functional/baseline-default/collections/ns2/col/foo_module.rst b/tests/functional/baseline-default/collections/ns2/col/foo_module.rst index bc56405a..49f4e39d 100644 --- a/tests/functional/baseline-default/collections/ns2/col/foo_module.rst +++ b/tests/functional/baseline-default/collections/ns2/col/foo_module.rst @@ -71,6 +71,7 @@ Synopsis - Does some foo on the remote host. - Whether foo is magic or not has not yet been determined. +- \ :ansenvvarref:`FOOBAR1`\ , \ :ansenvvarref:`FOOBAR2`\ , \ :ansenvvar:`FOOBAR3`\ , \ :ansenvvar:`FOOBAR4`\ . .. Aliases diff --git a/tests/functional/baseline-default/collections/ns2/flatcol/foo_module.rst b/tests/functional/baseline-default/collections/ns2/flatcol/foo_module.rst index 1d3e4dad..a585759b 100644 --- a/tests/functional/baseline-default/collections/ns2/flatcol/foo_module.rst +++ b/tests/functional/baseline-default/collections/ns2/flatcol/foo_module.rst @@ -261,6 +261,8 @@ Parameters Note that \ :ansopt:`ns2.flatcol.foo#module:subfoo.foo`\ is the same as \ :ansopt:`ns2.flatcol.foo#module:subbaz.foo`\ , \ :ansopt:`ns2.flatcol.foo#module:subbaz.bam`\ , and \ :ansopt:`ns2.flatcol.foo#module:subfoo.bam`\ . + \ :ansenvvarref:`FOOBAR1`\ , \ :ansenvvarref:`FOOBAR2`\ , \ :ansenvvar:`FOOBAR3`\ , \ :ansenvvar:`FOOBAR4`\ . + .. raw:: html diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/docsite/filter_guide.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/docsite/filter_guide.rst index 02b1bf67..0354846d 100644 --- a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/docsite/filter_guide.rst +++ b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/docsite/filter_guide.rst @@ -16,3 +16,15 @@ The :ref:`ns2.col collection ` offers two filters. - ``ns2.col.foo``: foo! - ``ns2.col.bar``: bar! + +.. envvar:: FOOBAR1 + + This is one environment variable. + +.. envvar:: FOOBAR2 + + This is another environment variable. + +.. envvar:: FOOBAR3 + + This is a third environment variable. diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_module.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_module.rst index bc56405a..49f4e39d 100644 --- a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_module.rst +++ b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_module.rst @@ -71,6 +71,7 @@ Synopsis - Does some foo on the remote host. - Whether foo is magic or not has not yet been determined. +- \ :ansenvvarref:`FOOBAR1`\ , \ :ansenvvarref:`FOOBAR2`\ , \ :ansenvvar:`FOOBAR3`\ , \ :ansenvvar:`FOOBAR4`\ . .. Aliases diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/flatcol/foo_module.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/flatcol/foo_module.rst index 1d3e4dad..a585759b 100644 --- a/tests/functional/baseline-no-breadcrumbs/collections/ns2/flatcol/foo_module.rst +++ b/tests/functional/baseline-no-breadcrumbs/collections/ns2/flatcol/foo_module.rst @@ -261,6 +261,8 @@ Parameters Note that \ :ansopt:`ns2.flatcol.foo#module:subfoo.foo`\ is the same as \ :ansopt:`ns2.flatcol.foo#module:subbaz.foo`\ , \ :ansopt:`ns2.flatcol.foo#module:subbaz.bam`\ , and \ :ansopt:`ns2.flatcol.foo#module:subfoo.bam`\ . + \ :ansenvvarref:`FOOBAR1`\ , \ :ansenvvarref:`FOOBAR2`\ , \ :ansenvvar:`FOOBAR3`\ , \ :ansenvvar:`FOOBAR4`\ . + .. raw:: html diff --git a/tests/functional/baseline-no-indexes/collections/ns2/col/docsite/filter_guide.rst b/tests/functional/baseline-no-indexes/collections/ns2/col/docsite/filter_guide.rst index 02b1bf67..0354846d 100644 --- a/tests/functional/baseline-no-indexes/collections/ns2/col/docsite/filter_guide.rst +++ b/tests/functional/baseline-no-indexes/collections/ns2/col/docsite/filter_guide.rst @@ -16,3 +16,15 @@ The :ref:`ns2.col collection ` offers two filters. - ``ns2.col.foo``: foo! - ``ns2.col.bar``: bar! + +.. envvar:: FOOBAR1 + + This is one environment variable. + +.. envvar:: FOOBAR2 + + This is another environment variable. + +.. envvar:: FOOBAR3 + + This is a third environment variable. diff --git a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_module.rst b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_module.rst index bc56405a..49f4e39d 100644 --- a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_module.rst +++ b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_module.rst @@ -71,6 +71,7 @@ Synopsis - Does some foo on the remote host. - Whether foo is magic or not has not yet been determined. +- \ :ansenvvarref:`FOOBAR1`\ , \ :ansenvvarref:`FOOBAR2`\ , \ :ansenvvar:`FOOBAR3`\ , \ :ansenvvar:`FOOBAR4`\ . .. Aliases diff --git a/tests/functional/baseline-no-indexes/collections/ns2/flatcol/foo_module.rst b/tests/functional/baseline-no-indexes/collections/ns2/flatcol/foo_module.rst index 1d3e4dad..a585759b 100644 --- a/tests/functional/baseline-no-indexes/collections/ns2/flatcol/foo_module.rst +++ b/tests/functional/baseline-no-indexes/collections/ns2/flatcol/foo_module.rst @@ -261,6 +261,8 @@ Parameters Note that \ :ansopt:`ns2.flatcol.foo#module:subfoo.foo`\ is the same as \ :ansopt:`ns2.flatcol.foo#module:subbaz.foo`\ , \ :ansopt:`ns2.flatcol.foo#module:subbaz.bam`\ , and \ :ansopt:`ns2.flatcol.foo#module:subfoo.bam`\ . + \ :ansenvvarref:`FOOBAR1`\ , \ :ansenvvarref:`FOOBAR2`\ , \ :ansenvvar:`FOOBAR3`\ , \ :ansenvvar:`FOOBAR4`\ . + .. raw:: html diff --git a/tests/functional/baseline-squash-hierarchy/docsite/filter_guide.rst b/tests/functional/baseline-squash-hierarchy/docsite/filter_guide.rst index 02b1bf67..0354846d 100644 --- a/tests/functional/baseline-squash-hierarchy/docsite/filter_guide.rst +++ b/tests/functional/baseline-squash-hierarchy/docsite/filter_guide.rst @@ -16,3 +16,15 @@ The :ref:`ns2.col collection ` offers two filters. - ``ns2.col.foo``: foo! - ``ns2.col.bar``: bar! + +.. envvar:: FOOBAR1 + + This is one environment variable. + +.. envvar:: FOOBAR2 + + This is another environment variable. + +.. envvar:: FOOBAR3 + + This is a third environment variable. diff --git a/tests/functional/baseline-squash-hierarchy/foo_module.rst b/tests/functional/baseline-squash-hierarchy/foo_module.rst index bc56405a..49f4e39d 100644 --- a/tests/functional/baseline-squash-hierarchy/foo_module.rst +++ b/tests/functional/baseline-squash-hierarchy/foo_module.rst @@ -71,6 +71,7 @@ Synopsis - Does some foo on the remote host. - Whether foo is magic or not has not yet been determined. +- \ :ansenvvarref:`FOOBAR1`\ , \ :ansenvvarref:`FOOBAR2`\ , \ :ansenvvar:`FOOBAR3`\ , \ :ansenvvar:`FOOBAR4`\ . .. Aliases diff --git a/tests/functional/baseline-use-html-blobs/collections/ns2/col/docsite/filter_guide.rst b/tests/functional/baseline-use-html-blobs/collections/ns2/col/docsite/filter_guide.rst index 02b1bf67..0354846d 100644 --- a/tests/functional/baseline-use-html-blobs/collections/ns2/col/docsite/filter_guide.rst +++ b/tests/functional/baseline-use-html-blobs/collections/ns2/col/docsite/filter_guide.rst @@ -16,3 +16,15 @@ The :ref:`ns2.col collection ` offers two filters. - ``ns2.col.foo``: foo! - ``ns2.col.bar``: bar! + +.. envvar:: FOOBAR1 + + This is one environment variable. + +.. envvar:: FOOBAR2 + + This is another environment variable. + +.. envvar:: FOOBAR3 + + This is a third environment variable. diff --git a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_module.rst b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_module.rst index cabbfb21..deb93314 100644 --- a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_module.rst +++ b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_module.rst @@ -71,6 +71,7 @@ Synopsis - Does some foo on the remote host. - Whether foo is magic or not has not yet been determined. +- \ :ansenvvarref:`FOOBAR1`\ , \ :ansenvvarref:`FOOBAR2`\ , \ :ansenvvar:`FOOBAR3`\ , \ :ansenvvar:`FOOBAR4`\ . .. Aliases diff --git a/tests/functional/build-docs-baseline.sh b/tests/functional/build-docs-baseline.sh index b0ae55ec..5c0d2d01 100755 --- a/tests/functional/build-docs-baseline.sh +++ b/tests/functional/build-docs-baseline.sh @@ -19,7 +19,7 @@ make_docsite_baseline() { set -e ) - rstcheck --report-level warning --ignore-roles ansible-option-default,ansible-rv-sample-value,ansopt,ansval,ansretval,ansible-option-choices-entry-default,ansible-option-choices-entry -r "${DEST}" 2>&1 | ( + rstcheck --report-level warning --ignore-roles ansible-option-default,ansible-rv-sample-value,ansopt,ansval,ansretval,ansible-option-choices-entry-default,ansible-option-choices-entry,ansenvvar,ansenvvarref -r "${DEST}" 2>&1 | ( set +e grep -v "CRITICAL:rstcheck_core.checker:An \`AttributeError\` error occured." set -e diff --git a/tests/functional/collections/ansible_collections/ns2/col/docs/docsite/config.yml b/tests/functional/collections/ansible_collections/ns2/col/docs/docsite/config.yml new file mode 100644 index 00000000..22331168 --- /dev/null +++ b/tests/functional/collections/ansible_collections/ns2/col/docs/docsite/config.yml @@ -0,0 +1,8 @@ +--- +# 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 + +envvar_directives: + - FOOBAR1 + - FOOBAR2 diff --git a/tests/functional/collections/ansible_collections/ns2/col/docs/docsite/rst/filter_guide.rst b/tests/functional/collections/ansible_collections/ns2/col/docs/docsite/rst/filter_guide.rst index 02b1bf67..0354846d 100644 --- a/tests/functional/collections/ansible_collections/ns2/col/docs/docsite/rst/filter_guide.rst +++ b/tests/functional/collections/ansible_collections/ns2/col/docs/docsite/rst/filter_guide.rst @@ -16,3 +16,15 @@ The :ref:`ns2.col collection ` offers two filters. - ``ns2.col.foo``: foo! - ``ns2.col.bar``: bar! + +.. envvar:: FOOBAR1 + + This is one environment variable. + +.. envvar:: FOOBAR2 + + This is another environment variable. + +.. envvar:: FOOBAR3 + + This is a third environment variable. diff --git a/tests/functional/collections/ansible_collections/ns2/col/plugins/modules/foo.py b/tests/functional/collections/ansible_collections/ns2/col/plugins/modules/foo.py index afe3e1a2..ff1aa8c5 100644 --- a/tests/functional/collections/ansible_collections/ns2/col/plugins/modules/foo.py +++ b/tests/functional/collections/ansible_collections/ns2/col/plugins/modules/foo.py @@ -19,6 +19,7 @@ description: - Does some foo on the remote host. - Whether foo is magic or not has not yet been determined. + - E(FOOBAR1), E(FOOBAR2), E(FOOBAR3), E(FOOBAR4). options: foo: description: The foo source. diff --git a/tests/functional/collections/ansible_collections/ns2/flatcol/plugins/modules/foo.py b/tests/functional/collections/ansible_collections/ns2/flatcol/plugins/modules/foo.py index 6ea1a52d..b600300d 100644 --- a/tests/functional/collections/ansible_collections/ns2/flatcol/plugins/modules/foo.py +++ b/tests/functional/collections/ansible_collections/ns2/flatcol/plugins/modules/foo.py @@ -46,6 +46,7 @@ - Whatever. - Also required when O(subfoo) is specified when O(foo=bar) or V(baz). - Note that O(subfoo.foo) is the same as O(subbaz.foo), O(subbaz.bam), and O(subfoo.bam). + - E(FOOBAR1), E(FOOBAR2), E(FOOBAR3), E(FOOBAR4). type: str required: true aliases: