Plugin option config: fix bug, only show precendence note if necessary (#403)

* Fix bug that causes keyword configs to be hidden in special cases.

* Add changelog fragment for precendence note; only show note when necessary.

Author: felixfontein

changelogs/fragments/403-arguments.yml

@@ -0,0 +1,5 @@
+bugfixes:
+  - "Fix bug that hid keyword config for plugin options for options that are only configurable this way (https://github.com/ansible-community/antsibull-docs/pull/403)."
+minor_changes:
+  - "For plugin options that can be configured through other means (Ansible variables, INI entries, environment variables, keywords, CLI arguments), show a notice on precedence below the plugin's parameters if more than one such way is present for an option
+     (https://github.com/ansible-community/antsibull-docs/pull/400, https://github.com/ansible-community/antsibull-docs/pull/403)."

src/antsibull_docs/data/docsite/ansible-docsite/macros/parameters.rst.j2

@@ -110,7 +110,7 @@
       :ansible-option-default-bold:`Default:` :ansible-option-default:`@{ value['default'] | antsibull_to_json | rst_escape(escape_ending_whitespace=true) | rst_indent(6, blank=true) }@`
 {%   endif %}
 {#   Configuration #}
-{%   if plugin_type != 'module' and plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['cli']) %}
+{%   if plugin_type != 'module' and plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['keyword'] or value['cli']) %}
 
       .. rst-class:: ansible-option-line
 
@@ -239,7 +239,7 @@
       <p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">@{ value['default'] | antsibull_to_json | escape | rst_indent(6, blank=true) }@</code></p>
 {%   endif %}
 {#   Configuration #}
-{%   if plugin_type != 'module' and plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['cli']) %}
+{%   if plugin_type != 'module' and plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['keyword'] or value['cli']) %}
       <p class="ansible-option-line"><strong class="ansible-option-configuration">Configuration:</strong></p>
       <ul class="simple">
 {%     if value['ini'] %}

src/antsibull_docs/data/docsite/ansible-docsite/plugin.rst.j2

@@ -262,7 +262,7 @@ Parameters
 @{     parameters_rst(doc['options'] | remove_options_from_list(options_to_skip) | dictsort, suboption_key='suboptions') }@
 {%   endif %}
 {% endif %}
-{% if plugin_type != 'module' %}
+{% if plugin_type != 'module' and has_option_config_ambiguity %}
 
 .. note::
 

src/antsibull_docs/data/docsite/simplified-rst/macros/parameters.rst.j2

@@ -71,7 +71,7 @@
       <p style="margin-top: 8px;"><b style="color: blue;">Default:</b> <code style="color: blue;">@{ value['default'] | antsibull_to_json | escape | rst_indent(6, blank=true) }@</code></p>
 {%   endif %}
 {#   Configuration #}
-{%   if plugin_type != 'module' and plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['cli']) %}
+{%   if plugin_type != 'module' and plugin_type != 'role' and (value['ini'] or value['env'] or value['vars'] or value['keyword'] or value['cli']) %}
       <p style="margin-top: 8px;"><b>Configuration:</b></p>
       <ul>
 {%     if value['ini'] %}

src/antsibull_docs/data/docsite/simplified-rst/plugin.rst.j2

@@ -197,7 +197,7 @@ Parameters
 
 @{   parameters_html(doc['options'] | remove_options_from_list(options_to_skip) | dictsort, suboption_key='suboptions') }@
 {% endif %}
-{% if plugin_type != 'module' %}
+{% if plugin_type != 'module' and has_option_config_ambiguity %}
 
 .. note::
 

src/antsibull_docs/write_docs/plugins.py

@@ -120,6 +120,22 @@ def guess_relative_filename(
     return f"{plugin_dir}/{plugin_short_name}.py"
 
 
+def has_option_config_ambiguity(documentation: dict[str, t.Any]) -> bool:
+    if not isinstance(documentation.get("options"), Mapping):
+        return False
+    for option in documentation["options"].values():
+        count = 0
+        for cfg in ("ini", "env", "vars", "keyword", "cli"):
+            if isinstance(option.get(cfg), Sequence):
+                count += len(option[cfg])
+        if count > 1:
+            return True
+        # TODO: We do not recurse into option["suboptions"] (if exists),
+        #       since ansible-core's plugin manager does not handle these.
+        #       If this ever changes, this code should be adjusted.
+    return False
+
+
 def create_plugin_rst(
     collection_name: str,
     collection_meta: AnsibleCollectionMetadata,
@@ -253,6 +269,9 @@ def create_plugin_rst(
                 collection_communication=collection_links.communication,
                 collection_issue_tracker=collection_links.issue_tracker,
                 collection_deprecation_info=collection_meta.deprecation_info,
+                has_option_config_ambiguity=has_option_config_ambiguity(
+                    plugin_record["doc"]
+                ),
                 for_official_docsite=for_official_docsite,
                 add_version=add_version,
             )

tests/functional/ansible-doc-cache-all-others.json

@@ -1405,6 +1405,11 @@
      "options": {
       "bar": {
        "description": "Nothing.",
+       "env": [
+        {
+         "name": "FOO_BAR"
+        }
+       ],
        "type": "string"
       }
      },
@@ -10508,7 +10513,12 @@
       },
       "bar": {
        "description": "Foo bar.",
-       "type": "string"
+       "type": "string",
+       "vars": [
+        {
+         "name": "foo_bar"
+        }
+       ]
       }
      },
      "plugin_name": "ns2.col.foo",

tests/functional/ansible-doc-cache-all.json

@@ -1405,6 +1405,11 @@
      "options": {
       "bar": {
        "description": "Nothing.",
+       "env": [
+        {
+         "name": "FOO_BAR"
+        }
+       ],
        "type": "string"
       }
      },
@@ -10473,7 +10478,12 @@
       },
       "bar": {
        "description": "Foo bar.",
-       "type": "string"
+       "type": "string",
+       "vars": [
+        {
+         "name": "foo_bar"
+        }
+       ]
       }
      },
      "plugin_name": "ns2.col.foo",

tests/functional/ansible-doc-cache-ansible.builtin-ns.col2-ns2.col.json

@@ -1405,6 +1405,11 @@
      "options": {
       "bar": {
        "description": "Nothing.",
+       "env": [
+        {
+         "name": "FOO_BAR"
+        }
+       ],
        "type": "string"
       }
      },
@@ -10473,7 +10478,12 @@
       },
       "bar": {
        "description": "Foo bar.",
-       "type": "string"
+       "type": "string",
+       "vars": [
+        {
+         "name": "foo_bar"
+        }
+       ]
       }
      },
      "plugin_name": "ns2.col.foo",

tests/functional/ansible-doc-cache-ansible.builtin-ns2.col.json

@@ -1227,6 +1227,11 @@
      "options": {
       "bar": {
        "description": "Nothing.",
+       "env": [
+        {
+         "name": "FOO_BAR"
+        }
+       ],
        "type": "string"
       }
      },
@@ -10136,7 +10141,12 @@
       },
       "bar": {
        "description": "Foo bar.",
-       "type": "string"
+       "type": "string",
+       "vars": [
+        {
+         "name": "foo_bar"
+        }
+       ]
       }
      },
      "plugin_name": "ns2.col.foo",