Add param ordering note to plugins page. (#101)

* Add param ordering note to plugins.

Add a note to every filter, test, and lookup to list positional parameters before keyword ones.

* review suggestions

* Remove whitespace handling and lookup filter

* Adjust/fix examples, also support lookups better.

* Update baseline for tests.

* Adjust changelog fragment.

* Lookups have no positional parameters. (They have terms.)

* Support lookup terms.

* Be more explicit.

* Update baseline.

---------

Co-authored-by: Felix Fontein <[email protected]>

Author: Klaus Frank

changelogs/fragments/101-plugin-param-ordering-note.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - Add a note about the ordering of positional and named parameter to the plugin page. Also mention positional and keyword parameters for lookups (https://github.com/ansible-community/antsibull-docs/pull/101).

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

@@ -10,6 +10,8 @@
 {% from 'macros/returnvalues.rst.j2' import in_rst as return_docs_rst with context %}
 {% from 'macros/returnvalues.rst.j2' import in_html as return_docs_html with context %}
 {% from 'macros/version_added.rst.j2' import version_added_rst %}
+{% set has_positional_parameters = false %}
+{% set has_keyword_parameters = false %}
 .. Document meta
 
 :orphan:
@@ -196,6 +198,7 @@ The below requirements are needed on the local controller node that executes thi
 
 {% if doc['options']['_terms'] and plugin_type in ['lookup'] %}
 {%   set options_to_skip = options_to_skip + ['_terms'] %}
+{%   set has_positional_parameters = true %}
 
 .. Terms
 
@@ -220,7 +223,7 @@ Input
 
 {%   if plugin_type == 'filter' %}
 This describes the input of the filter, the value before ``| @{plugin_name}@``.
-{%   else %}
+{%   elif plugin_type == 'test' %}
 This describes the input of the test, the value before ``is @{plugin_name}@`` or ``is not @{plugin_name}@``.
 {%   endif %}
 
@@ -232,18 +235,20 @@ This describes the input of the test, the value before ``is @{plugin_name}@`` or
 
 {% endif %}
 
-{% if doc['positional'] and plugin_type in ['lookup', 'filter', 'test'] and doc['positional'] != ['_input'] %}
+{% if doc['positional'] and plugin_type in ['filter', 'test'] and doc['positional'] != ['_input'] %}
+{%   set has_positional_parameters = true %}
 {%   set options_to_skip = options_to_skip + doc['positional'] %}
 
 .. Positional
 
 Positional parameters
 ---------------------
 
+This describes positional parameters of the @{plugin_type}@. These are the values ``positional1``, ``positional2`` and so on in the following
 {%   if plugin_type == 'filter' %}
-This describes positional parameters of the filter. These are the values ``positional1``, ``positional2`` and so on in the following example: ``input | @{plugin_name}@(positional1, positional2, ...)``.
+example: ``input | @{plugin_name}@(positional1, positional2, ...)``
 {%   elif plugin_type == 'test' %}
-This describes positional parameters of the test. These are the values ``positional1``, ``positional2`` and so on in the following examples: ``input is @{plugin_name}@(positional1, positional2, ...)`` and ``input is not @{plugin_name}@(positional1, positional2, ...)``.
+examples: ``input is @{plugin_name}@(positional1, positional2, ...)`` and ``input is not @{plugin_name}@(positional1, positional2, ...)``
 {%   endif %}
 
 {%   if use_html_blobs %}
@@ -257,21 +262,25 @@ This describes positional parameters of the test. These are the values ``positio
 .. Options
 
 {% if doc['options'] | remove_options_from_list(options_to_skip) -%}
+{%   set has_keyword_parameters = true -%}
 
-{%   if plugin_type in ['filter', 'test'] %}
+{%   if plugin_type in ['lookup', 'filter', 'test'] %}
 Keyword parameters
 ------------------
+
+This describes keyword parameters of the @{plugin_type}@. These are the values ``key1=value1``, ``key2=value2`` and so on in the following
+{%     if plugin_type == 'filter' %}
+example: ``input | @{plugin_name}@(key1=value1, key2=value2, ...)``
+{%     elif plugin_type == 'test' %}
+examples: ``input is @{plugin_name}@(key1=value1, key2=value2, ...)`` and ``input is not @{plugin_name}@(key1=value1, key2=value2, ...)``
+{%     elif plugin_type == 'lookup' %}
+examples: ``lookup('@{plugin_name}@', key1=value1, key2=value2, ...)`` and ``query('@{plugin_name}@', key1=value1, key2=value2, ...)``
+{%     endif %}
 {%   else %}
 Parameters
 ----------
 {%   endif %}
 
-{%   if plugin_type == 'filter' %}
-This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following example: ``input | @{plugin_name}@(key1=value1, key2=value2, ...)``.
-{%   elif plugin_type == 'test' %}
-This describes keyword parameters of the test. These are the values ``key1=value1``, ``key2=value2`` and so on in the following examples: ``input is @{plugin_name}@(key1=value1, key2=value2, ...)`` and ``input is not @{plugin_name}@(key1=value1, key2=value2, ...)``.
-{%   endif %}
-
 {%   if use_html_blobs %}
 @{     parameters_html(doc['options'] | remove_options_from_list(options_to_skip) | dictsort, suboption_key='suboptions') }@
 {%   else %}
@@ -291,14 +300,26 @@ Attributes
 
 .. Notes
 
-{% if doc['notes'] -%}
+{% if doc['notes'] or (has_positional_parameters and has_keyword_parameters) -%}
 Notes
 -----
 
 .. note::
-{%   for note in doc['notes'] %}
+{%   if has_positional_parameters and has_keyword_parameters %}
+   - When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters:
+{%     if plugin_type == 'filter' %}
+     ``input | @{plugin_name}@(positional1, positional2, key1=value1, key2=value2)``
+{%     elif plugin_type == 'test' %}
+     ``input is @{plugin_name}@(positional1, positional2, key1=value1, key2=value2)`` and ``input is not @{plugin_name}@(positional1, positional2, key1=value1, key2=value2)``
+{%     elif plugin_type == 'lookup' %}
+     ``lookup('@{plugin_name}@', term1, term2, key1=value1, key2=value2)`` and ``query('@{plugin_name}@', term1, term2, key1=value1, key2=value2)``
+{%     endif %}
+{%   endif %}
+{%   if doc['notes'] %}
+{%     for note in doc['notes'] %}
    - @{ note | rst_ify | indent(width=5) }@
-{%   endfor %}
+{%     endfor %}
+{%   endif %}
 {% endif %}
 
 .. Seealso

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

@@ -83,7 +83,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

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

@@ -85,7 +85,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

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

@@ -91,7 +91,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

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

@@ -85,7 +85,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

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

@@ -141,7 +141,8 @@ This describes the input of the filter, the value before ``| ns2.col.foo``.
 Keyword parameters
 ------------------
 
-This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following example: ``input | ns2.col.foo(key1=value1, key2=value2, ...)``.
+This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following
+example: ``input | ns2.col.foo(key1=value1, key2=value2, ...)``
 
 .. rst-class:: ansible-option-table
 

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

@@ -85,7 +85,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

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

@@ -137,9 +137,11 @@ Terms
 
 .. Options
 
-Parameters
-----------
+Keyword parameters
+------------------
 
+This describes keyword parameters of the lookup. These are the values ``key1=value1``, ``key2=value2`` and so on in the following
+examples: ``lookup('ns2.col.foo', key1=value1, key2=value2, ...)`` and ``query('ns2.col.foo', key1=value1, key2=value2, ...)``
 
 .. rst-class:: ansible-option-table
 
@@ -194,6 +196,12 @@ Parameters
 
 .. Notes
 
+Notes
+-----
+
+.. note::
+   - When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters:
+     ``lookup('ns2.col.foo', term1, term2, key1=value1, key2=value2)`` and ``query('ns2.col.foo', term1, term2, key1=value1, key2=value2)``
 
 .. Seealso
 

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

@@ -96,7 +96,6 @@ The below requirements are needed on the host that executes this module.
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

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

@@ -85,7 +85,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

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

@@ -138,7 +138,8 @@ This describes the input of the test, the value before ``is ns2.col.foo`` or ``i
 Keyword parameters
 ------------------
 
-This describes keyword parameters of the test. These are the values ``key1=value1``, ``key2=value2`` and so on in the following examples: ``input is ns2.col.foo(key1=value1, key2=value2, ...)`` and ``input is not ns2.col.foo(key1=value1, key2=value2, ...)``.
+This describes keyword parameters of the test. These are the values ``key1=value1``, ``key2=value2`` and so on in the following
+examples: ``input is ns2.col.foo(key1=value1, key2=value2, ...)`` and ``input is not ns2.col.foo(key1=value1, key2=value2, ...)``
 
 .. rst-class:: ansible-option-table
 

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

@@ -96,7 +96,6 @@ The below requirements are needed on the local controller node that executes thi
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_become.rst

@@ -83,7 +83,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_cache.rst

@@ -85,7 +85,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_callback.rst

@@ -91,7 +91,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_connection.rst

@@ -85,7 +85,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_filter.rst

@@ -141,7 +141,8 @@ This describes the input of the filter, the value before ``| ns2.col.foo``.
 Keyword parameters
 ------------------
 
-This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following example: ``input | ns2.col.foo(key1=value1, key2=value2, ...)``.
+This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following
+example: ``input | ns2.col.foo(key1=value1, key2=value2, ...)``
 
 .. rst-class:: ansible-option-table
 

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_inventory.rst

@@ -85,7 +85,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_lookup.rst

@@ -137,9 +137,11 @@ Terms
 
 .. Options
 
-Parameters
-----------
+Keyword parameters
+------------------
 
+This describes keyword parameters of the lookup. These are the values ``key1=value1``, ``key2=value2`` and so on in the following
+examples: ``lookup('ns2.col.foo', key1=value1, key2=value2, ...)`` and ``query('ns2.col.foo', key1=value1, key2=value2, ...)``
 
 .. rst-class:: ansible-option-table
 
@@ -194,6 +196,12 @@ Parameters
 
 .. Notes
 
+Notes
+-----
+
+.. note::
+   - When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters:
+     ``lookup('ns2.col.foo', term1, term2, key1=value1, key2=value2)`` and ``query('ns2.col.foo', term1, term2, key1=value1, key2=value2)``
 
 .. Seealso
 

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_module.rst

@@ -96,7 +96,6 @@ The below requirements are needed on the host that executes this module.
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_shell.rst

@@ -85,7 +85,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_test.rst

@@ -138,7 +138,8 @@ This describes the input of the test, the value before ``is ns2.col.foo`` or ``i
 Keyword parameters
 ------------------
 
-This describes keyword parameters of the test. These are the values ``key1=value1``, ``key2=value2`` and so on in the following examples: ``input is ns2.col.foo(key1=value1, key2=value2, ...)`` and ``input is not ns2.col.foo(key1=value1, key2=value2, ...)``.
+This describes keyword parameters of the test. These are the values ``key1=value1``, ``key2=value2`` and so on in the following
+examples: ``input is ns2.col.foo(key1=value1, key2=value2, ...)`` and ``input is not ns2.col.foo(key1=value1, key2=value2, ...)``
 
 .. rst-class:: ansible-option-table
 

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_vars.rst

@@ -96,7 +96,6 @@ The below requirements are needed on the local controller node that executes thi
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

tests/functional/baseline-no-indexes/collections/ns2/col/foo_become.rst

@@ -83,7 +83,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

tests/functional/baseline-no-indexes/collections/ns2/col/foo_cache.rst

@@ -85,7 +85,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

tests/functional/baseline-no-indexes/collections/ns2/col/foo_callback.rst

@@ -91,7 +91,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

tests/functional/baseline-no-indexes/collections/ns2/col/foo_connection.rst

@@ -85,7 +85,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::

tests/functional/baseline-no-indexes/collections/ns2/col/foo_filter.rst

@@ -141,7 +141,8 @@ This describes the input of the filter, the value before ``| ns2.col.foo``.
 Keyword parameters
 ------------------
 
-This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following example: ``input | ns2.col.foo(key1=value1, key2=value2, ...)``.
+This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following
+example: ``input | ns2.col.foo(key1=value1, key2=value2, ...)``
 
 .. rst-class:: ansible-option-table
 

tests/functional/baseline-no-indexes/collections/ns2/col/foo_inventory.rst

@@ -85,7 +85,6 @@ Synopsis
 Parameters
 ----------
 
-
 .. rst-class:: ansible-option-table
 
 .. list-table::