Plugin option config: fix bug, only show precendence note if necessary

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",

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

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

tests/functional/ansible-doc-cache-ns.col1-ns2.col-ns2.flatcol.json

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

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

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

tests/functional/baseline-default/collections/environment_variables.rst

@@ -41,3 +41,9 @@ Environment variables used by the ansible-core configuration are documented in :
 
     *Used by:*
     :ansplugin:`ns2.col.foo shell plugin <ns2.col.foo#shell>`
+.. envvar:: FOO_BAR
+
+    Nothing.
+
+    *Used by:*
+    :ansplugin:`ns2.col.foo callback plugin <ns2.col.foo#callback>`

tests/functional/baseline-default/collections/ns2/col/bar_filter.rst

@@ -300,13 +300,6 @@ example: ``input | ns2.col.bar(key1=value1, key2=value2, ...)``
         </div>
 
 
-.. note::
-
-    Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order.
-    For example, a variable that is lower in the list will override a variable that is higher up.
-    The entry types are also ordered by precedence from low to high priority order.
-    For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).
-
 .. Attributes
 
 

tests/functional/baseline-default/collections/ns2/col/bar_test.rst

@@ -121,13 +121,6 @@ This describes the input of the test, the value before ``is ns2.col.bar`` or ``i
 .. Options
 
 
-.. note::
-
-    Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order.
-    For example, a variable that is lower in the list will override a variable that is higher up.
-    The entry types are also ordered by precedence from low to high priority order.
-    For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).
-
 .. Attributes
 
 

tests/functional/baseline-default/collections/ns2/col/foo_callback.rst

@@ -118,17 +118,17 @@ Parameters
       Nothing.
 
 
-      .. raw:: html
+      .. rst-class:: ansible-option-line
 
-        </div>
+      :ansible-option-configuration:`Configuration:`
 
+      - Environment variable: :envvar:`FOO\_BAR`
 
-.. note::
 
-    Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order.
-    For example, a variable that is lower in the list will override a variable that is higher up.
-    The entry types are also ordered by precedence from low to high priority order.
-    For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).
+      .. raw:: html
+
+        </div>
+
 
 .. Attributes
 

tests/functional/baseline-default/collections/ns2/col/foo_cliconf.rst

@@ -63,13 +63,6 @@ Synopsis
 .. Options
 
 
-.. note::
-
-    Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order.
-    For example, a variable that is lower in the list will override a variable that is higher up.
-    The entry types are also ordered by precedence from low to high priority order.
-    For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).
-
 .. Attributes
 
 

tests/functional/baseline-default/collections/ns2/col/foo_filter.rst

@@ -214,13 +214,6 @@ example: ``input | ns2.col.foo(key1=value1, key2=value2, ...)``
         </div>
 
 
-.. note::
-
-    Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order.
-    For example, a variable that is lower in the list will override a variable that is higher up.
-    The entry types are also ordered by precedence from low to high priority order.
-    For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).
-
 .. Attributes
 
 

tests/functional/baseline-default/collections/ns2/col/foo_inventory.rst

@@ -117,13 +117,6 @@ Parameters
         </div>
 
 
-.. note::
-
-    Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order.
-    For example, a variable that is lower in the list will override a variable that is higher up.
-    The entry types are also ordered by precedence from low to high priority order.
-    For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).
-
 .. Attributes
 
 

tests/functional/baseline-default/collections/ns2/col/foo_lookup.rst

@@ -171,17 +171,17 @@ examples: ``lookup('ns2.col.foo', key1=value1, key2=value2, ...)`` and ``query('
       Foo bar.
 
 
-      .. raw:: html
+      .. rst-class:: ansible-option-line
 
-        </div>
+      :ansible-option-configuration:`Configuration:`
 
+      - Variable: foo\_bar
 
-.. note::
 
-    Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order.
-    For example, a variable that is lower in the list will override a variable that is higher up.
-    The entry types are also ordered by precedence from low to high priority order.
-    For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).
+      .. raw:: html
+
+        </div>
+
 
 .. Attributes