plugins (become, callback, filter): style adjustments (#9535)

* plugins (become, callback, filter, inventory): style adjustments

* remove inventory plugins from PR

* adjustments from review

* typo

plugins/become/pfexec.py

@@ -15,8 +15,8 @@ options:
   become_user:
     description:
       - User you 'become' to execute the task.
-      - This plugin ignores this setting as pfexec uses its own C(exec_attr) to figure this out, but it is supplied here
+      - This plugin ignores this setting as pfexec uses its own C(exec_attr) to figure this out, but it is supplied here for
-        for Ansible to make decisions needed for the task execution, like file permissions.
+        Ansible to make decisions needed for the task execution, like file permissions.
     type: string
     default: root
     ini:

plugins/callback/default_without_diff.py

@@ -29,7 +29,7 @@ ansible_config: |
   stdout_callback = community.general.default_without_diff
 
 # Enable callback with environment variables:
-environment_variable: |
+environment_variable: |-
   ANSIBLE_STDOUT_CALLBACK=community.general.default_without_diff
 """
 

plugins/callback/yaml.py

@@ -14,7 +14,8 @@ type: stdout
 short_description: YAML-ized Ansible screen output
 deprecated:
   removed_in: 13.0.0
-  why: Starting in ansible-core 2.13, the P(ansible.builtin.default#callback) callback has support for printing output in YAML format.
+  why: Starting in ansible-core 2.13, the P(ansible.builtin.default#callback) callback has support for printing output in
+    YAML format.
   alternative: Use O(ansible.builtin.default#callback:result_format=yaml).
 description:
   - Ansible output that can be quite a bit easier to read than the default JSON formatting.

plugins/filter/accumulate.py

@@ -2,43 +2,44 @@
 # 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
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: accumulate
+name: accumulate
-  short_description: Produce a list of accumulated sums of the input list contents
+short_description: Produce a list of accumulated sums of the input list contents
-  version_added: 10.1.0
+version_added: 10.1.0
-  author: Max Gautier (@VannTen)
+author: Max Gautier (@VannTen)
-  description:
+description:
-    - Passthrough to the L(Python itertools.accumulate function,https://docs.python.org/3/library/itertools.html#itertools.accumulate).
+  - Passthrough to the L(Python itertools.accumulate function,https://docs.python.org/3/library/itertools.html#itertools.accumulate).
-    - Transforms an input list into the cumulative list of results from applying addition to the elements of the input list.
+  - Transforms an input list into the cumulative list of results from applying addition to the elements of the input list.
-    - Addition means the default Python implementation of C(+) for input list elements type.
+  - Addition means the default Python implementation of C(+) for input list elements type.
-  options:
+options:
-    _input:
+  _input:
-      description: A list.
+    description: A list.
-      type: list
-      elements: any
-      required: true
-'''
-
-RETURN = '''
-  _value:
-    description: A list of cumulated sums of the elements of the input list.
     type: list
     elements: any
-'''
+    required: true
+"""
 
-EXAMPLES = '''
+RETURN = r"""
+_value:
+  description: A list of cumulated sums of the elements of the input list.
+  type: list
+  elements: any
+"""
+
+EXAMPLES = r"""
 - name: Enumerate parent directories of some path
   ansible.builtin.debug:
     var: >
-       "/some/path/to/my/file"
+      "/some/path/to/my/file"
-       | split('/') | map('split', '/')
+      | split('/') | map('split', '/')
-       | community.general.accumulate | map('join', '/')
+      | community.general.accumulate | map('join', '/')
     # Produces: ['', '/some', '/some/path', '/some/path/to', '/some/path/to/my', '/some/path/to/my/file']
+
 - name: Growing string
   ansible.builtin.debug:
     var: "'abc' | community.general.accumulate"
     # Produces ['a', 'ab', 'abc']
-'''
+"""
 
 from itertools import accumulate
 from collections.abc import Sequence

plugins/filter/counter.py

@@ -6,34 +6,35 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: counter
+name: counter
-  short_description: Counts hashable elements in a sequence
+short_description: Counts hashable elements in a sequence
-  version_added: 4.3.0
+version_added: 4.3.0
-  author: Rémy Keil (@keilr)
+author: Rémy Keil (@keilr)
-  description:
+description:
-    - Counts hashable elements in a sequence.
+  - Counts hashable elements in a sequence.
-  options:
+options:
-    _input:
+  _input:
-      description: A sequence.
+    description: A sequence.
-      type: list
+    type: list
-      elements: any
+    elements: any
-      required: true
+    required: true
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Count occurrences
   ansible.builtin.debug:
     msg: >-
       {{ [1, 'a', 2, 2, 'a', 'b', 'a'] | community.general.counter }}
     # Produces: {1: 1, 'a': 3, 2: 2, 'b': 1}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: A dictionary with the elements of the sequence as keys, and their number of occurrences in the sequence as values.
+  description: A dictionary with the elements of the sequence as keys, and their number of occurrences in the sequence as
-    type: dictionary
+    values.
-'''
+  type: dictionary
+"""
 
 from ansible.errors import AnsibleFilterError
 from ansible.module_utils.common._collections_compat import Sequence

plugins/filter/crc32.py

@@ -16,33 +16,33 @@ except ImportError:
     HAS_ZLIB = False
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: crc32
+name: crc32
-  short_description: Generate a CRC32 checksum
+short_description: Generate a CRC32 checksum
-  version_added: 5.4.0
+version_added: 5.4.0
-  description:
+description:
-    - Checksum a string using CRC32 algorithm and return its hexadecimal representation.
+  - Checksum a string using CRC32 algorithm and return its hexadecimal representation.
-  options:
+options:
-    _input:
+  _input:
-      description:
+    description:
-        - The string to checksum.
+      - The string to checksum.
-      type: string
-      required: true
-  author:
-    - Julien Riou
-'''
-
-EXAMPLES = '''
-  - name: Checksum a test string
-    ansible.builtin.debug:
-      msg: "{{ 'test' | community.general.crc32 }}"
-'''
-
-RETURN = '''
-  _value:
-    description: CRC32 checksum.
     type: string
-'''
+    required: true
+author:
+  - Julien Riou
+"""
+
+EXAMPLES = r"""
+- name: Checksum a test string
+  ansible.builtin.debug:
+    msg: "{{ 'test' | community.general.crc32 }}"
+"""
+
+RETURN = r"""
+_value:
+  description: CRC32 checksum.
+  type: string
+"""
 
 
 def crc32s(value):

plugins/filter/dict.py

@@ -7,22 +7,22 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: dict
+name: dict
-  short_description: Convert a list of tuples into a dictionary
+short_description: Convert a list of tuples into a dictionary
-  version_added: 3.0.0
+version_added: 3.0.0
-  author: Felix Fontein (@felixfontein)
+author: Felix Fontein (@felixfontein)
-  description:
+description:
-    - Convert a list of tuples into a dictionary. This is a filter version of the C(dict) function.
+  - Convert a list of tuples into a dictionary. This is a filter version of the C(dict) function.
-  options:
+options:
-    _input:
+  _input:
-      description: A list of tuples (with exactly two elements).
+    description: A list of tuples (with exactly two elements).
-      type: list
+    type: list
-      elements: tuple
+    elements: tuple
-      required: true
+    required: true
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Convert list of tuples into dictionary
   ansible.builtin.set_fact:
     dictionary: "{{ [[1, 2], ['a', 'b']] | community.general.dict }}"
@@ -53,13 +53,13 @@ EXAMPLES = '''
   #     "k2": 42,
   #     "k3": "b"
   #   }
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: A dictionary with the provided key-value pairs.
+  description: A dictionary with the provided key-value pairs.
-    type: dictionary
+  type: dictionary
-'''
+"""
 
 
 def dict_filter(sequence):

plugins/filter/dict_kv.py

@@ -6,37 +6,37 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: dict_kv
+name: dict_kv
-  short_description: Convert a value to a dictionary with a single key-value pair
+short_description: Convert a value to a dictionary with a single key-value pair
-  version_added: 1.3.0
+version_added: 1.3.0
-  author: Stanislav German-Evtushenko (@giner)
+author: Stanislav German-Evtushenko (@giner)
-  description:
+description:
-    - Convert a value to a dictionary with a single key-value pair.
+  - Convert a value to a dictionary with a single key-value pair.
-  positional: key
+positional: key
-  options:
+options:
-    _input:
+  _input:
-      description: The value for the single key-value pair.
+    description: The value for the single key-value pair.
-      type: any
+    type: any
-      required: true
+    required: true
-    key:
+  key:
-      description: The key for the single key-value pair.
+    description: The key for the single key-value pair.
-      type: any
+    type: any
-      required: true
+    required: true
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Create a one-element dictionary from a value
   ansible.builtin.debug:
     msg: "{{ 'myvalue' | dict_kv('mykey') }}"
     # Produces the dictionary {'mykey': 'myvalue'}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: A dictionary with a single key-value pair.
+  description: A dictionary with a single key-value pair.
-    type: dictionary
+  type: dictionary
-'''
+"""
 
 
 def dict_kv(value, key):

plugins/filter/from_csv.py

@@ -8,51 +8,51 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: from_csv
+name: from_csv
-  short_description: Converts CSV text input into list of dicts
+short_description: Converts CSV text input into list of dicts
-  version_added: 2.3.0
+version_added: 2.3.0
-  author: Andrew Pantuso (@Ajpantuso)
+author: Andrew Pantuso (@Ajpantuso)
-  description:
+description:
-    - Converts CSV text input into list of dictionaries.
+  - Converts CSV text input into list of dictionaries.
-  options:
+options:
-    _input:
+  _input:
-      description: A string containing a CSV document.
+    description: A string containing a CSV document.
-      type: string
+    type: string
-      required: true
+    required: true
-    dialect:
+  dialect:
-      description:
+    description:
-        - The CSV dialect to use when parsing the CSV file.
+      - The CSV dialect to use when parsing the CSV file.
-        - Possible values include V(excel), V(excel-tab) or V(unix).
+      - Possible values include V(excel), V(excel-tab) or V(unix).
-      type: str
+    type: str
-      default: excel
+    default: excel
-    fieldnames:
+  fieldnames:
-      description:
+    description:
-        - A list of field names for every column.
+      - A list of field names for every column.
-        - This is needed if the CSV does not have a header.
+      - This is needed if the CSV does not have a header.
-      type: list
+    type: list
-      elements: str
+    elements: str
-    delimiter:
+  delimiter:
-      description:
+    description:
-        - A one-character string used to separate fields.
+      - A one-character string used to separate fields.
-        - When using this parameter, you change the default value used by O(dialect).
+      - When using this parameter, you change the default value used by O(dialect).
-        - The default value depends on the dialect used.
+      - The default value depends on the dialect used.
-      type: str
+    type: str
-    skipinitialspace:
+  skipinitialspace:
-      description:
+    description:
-        - Whether to ignore any whitespaces immediately following the delimiter.
+      - Whether to ignore any whitespaces immediately following the delimiter.
-        - When using this parameter, you change the default value used by O(dialect).
+      - When using this parameter, you change the default value used by O(dialect).
-        - The default value depends on the dialect used.
+      - The default value depends on the dialect used.
-      type: bool
+    type: bool
-    strict:
+  strict:
-      description:
+    description:
-        - Whether to raise an exception on bad CSV input.
+      - Whether to raise an exception on bad CSV input.
-        - When using this parameter, you change the default value used by O(dialect).
+      - When using this parameter, you change the default value used by O(dialect).
-        - The default value depends on the dialect used.
+      - The default value depends on the dialect used.
-      type: bool
+    type: bool
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Parse a CSV file's contents
   ansible.builtin.debug:
     msg: >-
@@ -71,14 +71,14 @@ EXAMPLES = '''
   #     "Column 1": "bar",
   #     "Value": "42",
   #   }
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: A list with one dictionary per row.
+  description: A list with one dictionary per row.
-    type: list
+  type: list
-    elements: dictionary
+  elements: dictionary
-'''
+"""
 
 from ansible.errors import AnsibleFilterError
 

plugins/filter/from_ini.py

@@ -6,43 +6,43 @@
 
 from __future__ import absolute_import, division, print_function
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
-  name: from_ini
+name: from_ini
-  short_description: Converts INI text input into a dictionary
+short_description: Converts INI text input into a dictionary
-  version_added: 8.2.0
+version_added: 8.2.0
-  author: Steffen Scheib (@sscheib)
+author: Steffen Scheib (@sscheib)
-  description:
+description:
-    - Converts INI text input into a dictionary.
+  - Converts INI text input into a dictionary.
-  options:
+options:
-    _input:
+  _input:
-      description: A string containing an INI document.
+    description: A string containing an INI document.
-      type: string
+    type: string
-      required: true
+    required: true
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
-  - name: Slurp an INI file
+- name: Slurp an INI file
-    ansible.builtin.slurp:
+  ansible.builtin.slurp:
-      src: /etc/rhsm/rhsm.conf
+    src: /etc/rhsm/rhsm.conf
-    register: rhsm_conf
+  register: rhsm_conf
 
-  - name: Display the INI file as dictionary
+- name: Display the INI file as dictionary
-    ansible.builtin.debug:
+  ansible.builtin.debug:
-      var: rhsm_conf.content | b64decode | community.general.from_ini
+    var: rhsm_conf.content | b64decode | community.general.from_ini
 
-  - name: Set a new dictionary fact with the contents of the INI file
+- name: Set a new dictionary fact with the contents of the INI file
-    ansible.builtin.set_fact:
+  ansible.builtin.set_fact:
-      rhsm_dict: >-
+    rhsm_dict: >-
-        {{
+      {{
-            rhsm_conf.content | b64decode | community.general.from_ini
+          rhsm_conf.content | b64decode | community.general.from_ini
-        }}
+      }}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: A dictionary representing the INI file.
+  description: A dictionary representing the INI file.
-    type: dictionary
+  type: dictionary
-'''
+"""
 
 __metaclass__ = type
 

plugins/filter/groupby_as_dict.py

@@ -6,29 +6,29 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: groupby_as_dict
+name: groupby_as_dict
-  short_description: Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute
+short_description: Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute
-  version_added: 3.1.0
+version_added: 3.1.0
-  author: Felix Fontein (@felixfontein)
+author: Felix Fontein (@felixfontein)
-  description:
+description:
-    - Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute.
+  - Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute.
-    - This filter is similar to the Jinja2 C(groupby) filter. Use the Jinja2 C(groupby) filter if you have multiple entries with the same value,
+  - This filter is similar to the Jinja2 C(groupby) filter. Use the Jinja2 C(groupby) filter if you have multiple entries
-      or when you need a dictionary with list values, or when you need to use deeply nested attributes.
+    with the same value, or when you need a dictionary with list values, or when you need to use deeply nested attributes.
-  positional: attribute
+positional: attribute
-  options:
+options:
-    _input:
+  _input:
-      description: A list of dictionaries
+    description: A list of dictionaries.
-      type: list
+    type: list
-      elements: dictionary
+    elements: dictionary
-      required: true
+    required: true
-    attribute:
+  attribute:
-      description: The attribute to use as the key.
+    description: The attribute to use as the key.
-      type: str
+    type: str
-      required: true
+    required: true
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Arrange a list of dictionaries as a dictionary of dictionaries
   ansible.builtin.debug:
     msg: "{{ sequence | community.general.groupby_as_dict('key') }}"
@@ -46,13 +46,13 @@ EXAMPLES = '''
   #  other_value:
   #    key: other_value
   #    baz: bar
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: A dictionary containing the dictionaries from the list as values.
+  description: A dictionary containing the dictionaries from the list as values.
-    type: dictionary
+  type: dictionary
-'''
+"""
 
 from ansible.errors import AnsibleFilterError
 from ansible.module_utils.common._collections_compat import Mapping, Sequence

plugins/filter/jc.py

@@ -8,41 +8,41 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: jc
+name: jc
-  short_description: Convert output of many shell commands and file-types to JSON
+short_description: Convert output of many shell commands and file-types to JSON
-  version_added: 1.1.0
+version_added: 1.1.0
-  author: Kelly Brazil (@kellyjonbrazil)
+author: Kelly Brazil (@kellyjonbrazil)
-  description:
+description:
-    - Convert output of many shell commands and file-types to JSON.
+  - Convert output of many shell commands and file-types to JSON.
-    - Uses the L(jc library,https://github.com/kellyjonbrazil/jc).
+  - Uses the L(jc library,https://github.com/kellyjonbrazil/jc).
-  positional: parser
+positional: parser
-  options:
+options:
-    _input:
+  _input:
-      description: The data to convert.
+    description: The data to convert.
-      type: string
+    type: string
-      required: true
+    required: true
-    parser:
+  parser:
-      description:
+    description:
-        - The correct parser for the input data.
+      - The correct parser for the input data.
-        - For example V(ifconfig).
+      - For example V(ifconfig).
-        - "Note: use underscores instead of dashes (if any) in the parser module name."
+      - 'Note: use underscores instead of dashes (if any) in the parser module name.'
-        - See U(https://github.com/kellyjonbrazil/jc#parsers) for the latest list of parsers.
+      - See U(https://github.com/kellyjonbrazil/jc#parsers) for the latest list of parsers.
-      type: string
+    type: string
-      required: true
+    required: true
-    quiet:
+  quiet:
-      description: Set to V(false) to not suppress warnings.
+    description: Set to V(false) to not suppress warnings.
-      type: boolean
+    type: boolean
-      default: true
+    default: true
-    raw:
+  raw:
-      description: Set to V(true) to return pre-processed JSON.
+    description: Set to V(true) to return pre-processed JSON.
-      type: boolean
+    type: boolean
-      default: false
+    default: false
-  requirements:
+requirements:
-    - jc installed as a Python library (U(https://pypi.org/project/jc/))
+  - jc installed as a Python library (U(https://pypi.org/project/jc/))
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Install the prereqs of the jc filter (jc Python package) on the Ansible controller
   delegate_to: localhost
   ansible.builtin.pip:
@@ -68,13 +68,13 @@ EXAMPLES = '''
   #   "operating_system": "GNU/Linux",
   #   "processor": "x86_64"
   # }
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: The processed output.
+  description: The processed output.
-    type: any
+  type: any
-'''
+"""
 
 from ansible.errors import AnsibleError, AnsibleFilterError
 import importlib

plugins/filter/json_query.py

@@ -6,29 +6,29 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: json_query
+name: json_query
-  short_description: Select a single element or a data subset from a complex data structure
+short_description: Select a single element or a data subset from a complex data structure
-  description:
+description:
-    - This filter lets you query a complex JSON structure and iterate over it using a loop structure.
+  - This filter lets you query a complex JSON structure and iterate over it using a loop structure.
-  positional: expr
+positional: expr
-  options:
+options:
-    _input:
+  _input:
-      description:
+    description:
-        - The JSON data to query.
+      - The JSON data to query.
-      type: any
+    type: any
-      required: true
+    required: true
-    expr:
+  expr:
-      description:
+    description:
-        - The query expression.
+      - The query expression.
-        - See U(http://jmespath.org/examples.html) for examples.
+      - See U(http://jmespath.org/examples.html) for examples.
-      type: string
+    type: string
-      required: true
+    required: true
-  requirements:
+requirements:
-    - jmespath
+  - jmespath
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Define data to work on in the examples below
   ansible.builtin.set_fact:
     domain_definition:
@@ -99,13 +99,13 @@ EXAMPLES = '''
     msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}"
   vars:
     server_name_query: "domain.server[?contains(name,'server1')].port"
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: The result of the query.
+  description: The result of the query.
-    type: any
+  type: any
-'''
+"""
 
 from ansible.errors import AnsibleError, AnsibleFilterError
 

plugins/filter/keep_keys.py

@@ -7,99 +7,99 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    name: keep_keys
+name: keep_keys
-    short_description: Keep specific keys from dictionaries in a list
+short_description: Keep specific keys from dictionaries in a list
-    version_added: "9.1.0"
+version_added: "9.1.0"
-    author:
+author:
-      - Vladimir Botka (@vbotka)
+  - Vladimir Botka (@vbotka)
-      - Felix Fontein (@felixfontein)
+  - Felix Fontein (@felixfontein)
-    description: This filter keeps only specified keys from a provided list of dictionaries.
+description: This filter keeps only specified keys from a provided list of dictionaries.
-    options:
+options:
-      _input:
+  _input:
-        description:
+    description:
-          - A list of dictionaries.
+      - A list of dictionaries.
-          - Top level keys must be strings.
+      - Top level keys must be strings.
-        type: list
+    type: list
-        elements: dictionary
+    elements: dictionary
-        required: true
+    required: true
-      target:
+  target:
-        description:
+    description:
-          - A single key or key pattern to keep, or a list of keys or keys patterns to keep.
+      - A single key or key pattern to keep, or a list of keys or keys patterns to keep.
-          - If O(matching_parameter=regex) there must be exactly one pattern provided.
+      - If O(matching_parameter=regex) there must be exactly one pattern provided.
-        type: raw
+    type: raw
-        required: true
+    required: true
-      matching_parameter:
+  matching_parameter:
-        description: Specify the matching option of target keys.
+    description: Specify the matching option of target keys.
-        type: str
+    type: str
-        default: equal
+    default: equal
-        choices:
+    choices:
-          equal: Matches keys of exactly one of the O(target) items.
+      equal: Matches keys of exactly one of the O(target) items.
-          starts_with: Matches keys that start with one of the O(target) items.
+      starts_with: Matches keys that start with one of the O(target) items.
-          ends_with: Matches keys that end with one of the O(target) items.
+      ends_with: Matches keys that end with one of the O(target) items.
-          regex:
+      regex:
-            - Matches keys that match the regular expresion provided in O(target).
+        - Matches keys that match the regular expresion provided in O(target).
-            - In this case, O(target) must be a regex string or a list with single regex string.
+        - In this case, O(target) must be a regex string or a list with single regex string.
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
-  l:
+- l:
     - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
     - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
 
   # 1) By default match keys that equal any of the items in the target.
-  t: [k0_x0, k1_x1]
+- t: [k0_x0, k1_x1]
   r: "{{ l | community.general.keep_keys(target=t) }}"
 
   # 2) Match keys that start with any of the items in the target.
-  t: [k0, k1]
+- t: [k0, k1]
   r: "{{ l | community.general.keep_keys(target=t, matching_parameter='starts_with') }}"
 
   # 3) Match keys that end with any of the items in target.
-  t: [x0, x1]
+- t: [x0, x1]
   r: "{{ l | community.general.keep_keys(target=t, matching_parameter='ends_with') }}"
 
   # 4) Match keys by the regex.
-  t: ['^.*[01]_x.*$']
+- t: ['^.*[01]_x.*$']
   r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}"
 
   # 5) Match keys by the regex.
-  t: '^.*[01]_x.*$'
+- t: '^.*[01]_x.*$'
   r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}"
 
   # The results of above examples 1-5 are all the same.
-  r:
+- r:
     - {k0_x0: A0, k1_x1: B0}
     - {k0_x0: A1, k1_x1: B1}
 
   # 6) By default match keys that equal the target.
-  t: k0_x0
+- t: k0_x0
   r: "{{ l | community.general.keep_keys(target=t) }}"
 
   # 7) Match keys that start with the target.
-  t: k0
+- t: k0
   r: "{{ l | community.general.keep_keys(target=t, matching_parameter='starts_with') }}"
 
   # 8) Match keys that end with the target.
-  t: x0
+- t: x0
   r: "{{ l | community.general.keep_keys(target=t, matching_parameter='ends_with') }}"
 
   # 9) Match keys by the regex.
-  t: '^.*0_x.*$'
+- t: '^.*0_x.*$'
   r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}"
 
   # The results of above examples 6-9 are all the same.
-  r:
+- r:
     - {k0_x0: A0}
     - {k0_x0: A1}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: The list of dictionaries with selected keys.
+  description: The list of dictionaries with selected keys.
-    type: list
+  type: list
-    elements: dictionary
+  elements: dictionary
-'''
+"""
 
 from ansible_collections.community.general.plugins.plugin_utils.keys_filter import (
     _keys_filter_params,

plugins/filter/lists_mergeby.py

@@ -6,65 +6,59 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: lists_mergeby
+name: lists_mergeby
-  short_description: Merge two or more lists of dictionaries by a given attribute
+short_description: Merge two or more lists of dictionaries by a given attribute
-  version_added: 2.0.0
+version_added: 2.0.0
-  author: Vladimir Botka (@vbotka)
+author: Vladimir Botka (@vbotka)
-  description:
+description:
-    - Merge two or more lists by attribute O(index). Optional
+  - Merge two or more lists by attribute O(index). Optional parameters O(recursive) and O(list_merge) control the merging
-      parameters O(recursive) and O(list_merge) control the merging of
+    of the nested dictionaries and lists.
-      the nested dictionaries and lists.
+  - The function C(merge_hash) from C(ansible.utils.vars) is used.
-    - The function C(merge_hash) from C(ansible.utils.vars) is used.
+  - To learn details on how to use the parameters O(recursive) and O(list_merge) see Ansible User's Guide chapter "Using filters
-    - To learn details on how to use the parameters O(recursive) and
+    to manipulate data" section R(Combining hashes/dictionaries, combine_filter) or the filter P(ansible.builtin.combine#filter).
-      O(list_merge) see Ansible User's Guide chapter "Using filters to
+positional: another_list, index
-      manipulate data" section R(Combining hashes/dictionaries, combine_filter) or the
+options:
-      filter P(ansible.builtin.combine#filter).
+  _input:
+    description:
+      - A list of dictionaries, or a list of lists of dictionaries.
+      - The required type of the C(elements) is set to C(raw) because all elements of O(_input) can be either dictionaries
+        or lists.
+    type: list
+    elements: raw
+    required: true
+  another_list:
+    description:
+      - Another list of dictionaries, or a list of lists of dictionaries.
+      - This parameter can be specified multiple times.
+    type: list
+    elements: raw
+  index:
+    description:
+      - The dictionary key that must be present in every dictionary in every list that is used to merge the lists.
+    type: string
+    required: true
+  recursive:
+    description:
+      - Should the combine recursively merge nested dictionaries (hashes).
+      - B(Note:) It does not depend on the value of the C(hash_behaviour) setting in C(ansible.cfg).
+    type: boolean
+    default: false
+  list_merge:
+    description:
+      - Modifies the behaviour when the dictionaries (hashes) to merge contain arrays/lists.
+    type: string
+    default: replace
+    choices:
+      - replace
+      - keep
+      - append
+      - prepend
+      - append_rp
+      - prepend_rp
+"""
 
-  positional: another_list, index
+EXAMPLES = r"""
-  options:
-    _input:
-      description:
-        - A list of dictionaries, or a list of lists of dictionaries.
-        - The required type of the C(elements) is set to C(raw)
-          because all elements of O(_input) can be either dictionaries
-          or lists.
-      type: list
-      elements: raw
-      required: true
-    another_list:
-      description:
-        - Another list of dictionaries, or a list of lists of dictionaries.
-        - This parameter can be specified multiple times.
-      type: list
-      elements: raw
-    index:
-      description:
-        - The dictionary key that must be present in every dictionary in every list that is used to
-          merge the lists.
-      type: string
-      required: true
-    recursive:
-      description:
-        - Should the combine recursively merge nested dictionaries (hashes).
-        - "B(Note:) It does not depend on the value of the C(hash_behaviour) setting in C(ansible.cfg)."
-      type: boolean
-      default: false
-    list_merge:
-      description:
-        - Modifies the behaviour when the dictionaries (hashes) to merge contain arrays/lists.
-      type: string
-      default: replace
-      choices:
-        - replace
-        - keep
-        - append
-        - prepend
-        - append_rp
-        - prepend_rp
-'''
-
-EXAMPLES = '''
 # Some results below are manually formatted for better readability. The
 # dictionaries' keys will be sorted alphabetically in real output.
 
@@ -193,14 +187,14 @@ EXAMPLES = '''
 #  r:
 #    - {index: a, foo: {x:1, y: 3, z: 4}}
 #    - {index: b, foo: [Y1, Y2]}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: The merged list.
+  description: The merged list.
-    type: list
+  type: list
-    elements: dictionary
+  elements: dictionary
-'''
+"""
 
 from ansible.errors import AnsibleFilterError
 from ansible.module_utils.six import string_types

plugins/filter/random_mac.py

@@ -7,25 +7,25 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: random_mac
+name: random_mac
-  short_description: Generate a random MAC address
+short_description: Generate a random MAC address
-  description:
+description:
-    - Generates random networking interfaces MAC addresses for a given prefix.
+  - Generates random networking interfaces MAC addresses for a given prefix.
-  options:
+options:
-    _input:
+  _input:
-      description: A string prefix to use as a basis for the random MAC generated.
+    description: A string prefix to use as a basis for the random MAC generated.
-      type: string
+    type: string
-      required: true
+    required: true
-    seed:
+  seed:
-      description:
+    description:
-        - A randomization seed to initialize the process, used to get repeatable results.
+      - A randomization seed to initialize the process, used to get repeatable results.
-        - If no seed is provided, a system random source such as C(/dev/urandom) is used.
+      - If no seed is provided, a system random source such as C(/dev/urandom) is used.
-      required: false
+    required: false
-      type: string
+    type: string
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Random MAC given a prefix
   ansible.builtin.debug:
     msg: "{{ '52:54:00' | community.general.random_mac }}"
@@ -34,13 +34,13 @@ EXAMPLES = '''
 - name: With a seed
   ansible.builtin.debug:
     msg: "{{ '52:54:00' | community.general.random_mac(seed=inventory_hostname) }}"
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: The generated MAC.
+  description: The generated MAC.
-    type: string
+  type: string
-'''
+"""
 
 import re
 from random import Random, SystemRandom

plugins/filter/remove_keys.py

@@ -7,99 +7,99 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    name: remove_keys
+name: remove_keys
-    short_description: Remove specific keys from dictionaries in a list
+short_description: Remove specific keys from dictionaries in a list
-    version_added: "9.1.0"
+version_added: "9.1.0"
-    author:
+author:
-      - Vladimir Botka (@vbotka)
+  - Vladimir Botka (@vbotka)
-      - Felix Fontein (@felixfontein)
+  - Felix Fontein (@felixfontein)
-    description: This filter removes only specified keys from a provided list of dictionaries.
+description: This filter removes only specified keys from a provided list of dictionaries.
-    options:
+options:
-      _input:
+  _input:
-        description:
+    description:
-          - A list of dictionaries.
+      - A list of dictionaries.
-          - Top level keys must be strings.
+      - Top level keys must be strings.
-        type: list
+    type: list
-        elements: dictionary
+    elements: dictionary
-        required: true
+    required: true
-      target:
+  target:
-        description:
+    description:
-          - A single key or key pattern to remove, or a list of keys or keys patterns to remove.
+      - A single key or key pattern to remove, or a list of keys or keys patterns to remove.
-          - If O(matching_parameter=regex) there must be exactly one pattern provided.
+      - If O(matching_parameter=regex) there must be exactly one pattern provided.
-        type: raw
+    type: raw
-        required: true
+    required: true
-      matching_parameter:
+  matching_parameter:
-        description: Specify the matching option of target keys.
+    description: Specify the matching option of target keys.
-        type: str
+    type: str
-        default: equal
+    default: equal
-        choices:
+    choices:
-          equal: Matches keys of exactly one of the O(target) items.
+      equal: Matches keys of exactly one of the O(target) items.
-          starts_with: Matches keys that start with one of the O(target) items.
+      starts_with: Matches keys that start with one of the O(target) items.
-          ends_with: Matches keys that end with one of the O(target) items.
+      ends_with: Matches keys that end with one of the O(target) items.
-          regex:
+      regex:
-            - Matches keys that match the regular expresion provided in O(target).
+        - Matches keys that match the regular expresion provided in O(target).
-            - In this case, O(target) must be a regex string or a list with single regex string.
+        - In this case, O(target) must be a regex string or a list with single regex string.
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
-  l:
+- l:
     - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
     - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
 
   # 1) By default match keys that equal any of the items in the target.
-  t: [k0_x0, k1_x1]
+- t: [k0_x0, k1_x1]
   r: "{{ l | community.general.remove_keys(target=t) }}"
 
   # 2) Match keys that start with any of the items in the target.
-  t: [k0, k1]
+- t: [k0, k1]
   r: "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}"
 
   # 3) Match keys that end with any of the items in target.
-  t: [x0, x1]
+- t: [x0, x1]
   r: "{{ l | community.general.remove_keys(target=t, matching_parameter='ends_with') }}"
 
   # 4) Match keys by the regex.
-  t: ['^.*[01]_x.*$']
+- t: ['^.*[01]_x.*$']
   r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}"
 
   # 5) Match keys by the regex.
-  t: '^.*[01]_x.*$'
+- t: '^.*[01]_x.*$'
   r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}"
 
   # The results of above examples 1-5 are all the same.
-  r:
+- r:
     - {k2_x2: [C0], k3_x3: foo}
     - {k2_x2: [C1], k3_x3: bar}
 
   # 6) By default match keys that equal the target.
-  t: k0_x0
+- t: k0_x0
   r: "{{ l | community.general.remove_keys(target=t) }}"
 
   # 7) Match keys that start with the target.
-  t: k0
+- t: k0
   r: "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}"
 
   # 8) Match keys that end with the target.
-  t: x0
+- t: x0
   r: "{{ l | community.general.remove_keys(target=t, matching_parameter='ends_with') }}"
 
   # 9) Match keys by the regex.
-  t: '^.*0_x.*$'
+- t: '^.*0_x.*$'
   r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}"
 
   # The results of above examples 6-9 are all the same.
-  r:
+- r:
     - {k1_x1: B0, k2_x2: [C0], k3_x3: foo}
     - {k1_x1: B1, k2_x2: [C1], k3_x3: bar}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: The list of dictionaries with selected keys removed.
+  description: The list of dictionaries with selected keys removed.
-    type: list
+  type: list
-    elements: dictionary
+  elements: dictionary
-'''
+"""
 
 from ansible_collections.community.general.plugins.plugin_utils.keys_filter import (
     _keys_filter_params,

plugins/filter/replace_keys.py

@@ -7,129 +7,129 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    name: replace_keys
+name: replace_keys
-    short_description: Replace specific keys in a list of dictionaries
+short_description: Replace specific keys in a list of dictionaries
-    version_added: "9.1.0"
+version_added: "9.1.0"
-    author:
+author:
-      - Vladimir Botka (@vbotka)
+  - Vladimir Botka (@vbotka)
-      - Felix Fontein (@felixfontein)
+  - Felix Fontein (@felixfontein)
-    description: This filter replaces specified keys in a provided list of dictionaries.
+description: This filter replaces specified keys in a provided list of dictionaries.
-    options:
+options:
-      _input:
+  _input:
+    description:
+      - A list of dictionaries.
+      - Top level keys must be strings.
+    type: list
+    elements: dictionary
+    required: true
+  target:
+    description:
+      - A list of dictionaries with attributes C(before) and C(after).
+      - The value of O(target[].after) replaces key matching O(target[].before).
+    type: list
+    elements: dictionary
+    required: true
+    suboptions:
+      before:
         description:
-          - A list of dictionaries.
+          - A key or key pattern to change.
-          - Top level keys must be strings.
+          - The interpretation of O(target[].before) depends on O(matching_parameter).
-        type: list
+          - For a key that matches multiple O(target[].before)s, the B(first) matching O(target[].after) will be used.
-        elements: dictionary
-        required: true
-      target:
-        description:
-          - A list of dictionaries with attributes C(before) and C(after).
-          - The value of O(target[].after) replaces key matching O(target[].before).
-        type: list
-        elements: dictionary
-        required: true
-        suboptions:
-          before:
-            description:
-              - A key or key pattern to change.
-              - The interpretation of O(target[].before) depends on O(matching_parameter).
-              - For a key that matches multiple O(target[].before)s, the B(first) matching O(target[].after) will be used.
-            type: str
-          after:
-            description: A matching key change to.
-            type: str
-      matching_parameter:
-        description: Specify the matching option of target keys.
         type: str
-        default: equal
+      after:
-        choices:
+        description: A matching key change to.
-          equal: Matches keys of exactly one of the O(target[].before) items.
+        type: str
-          starts_with: Matches keys that start with one of the O(target[].before) items.
+  matching_parameter:
-          ends_with: Matches keys that end with one of the O(target[].before) items.
+    description: Specify the matching option of target keys.
-          regex: Matches keys that match one of the regular expressions provided in O(target[].before).
+    type: str
-'''
+    default: equal
+    choices:
+      equal: Matches keys of exactly one of the O(target[].before) items.
+      starts_with: Matches keys that start with one of the O(target[].before) items.
+      ends_with: Matches keys that end with one of the O(target[].before) items.
+      regex: Matches keys that match one of the regular expressions provided in O(target[].before).
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
-  l:
+- l:
     - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
     - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
 
   # 1) By default, replace keys that are equal any of the attributes before.
-  t:
+- t:
     - {before: k0_x0, after: a0}
     - {before: k1_x1, after: a1}
   r: "{{ l | community.general.replace_keys(target=t) }}"
 
   # 2) Replace keys that starts with any of the attributes before.
-  t:
+- t:
     - {before: k0, after: a0}
     - {before: k1, after: a1}
   r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}"
 
   # 3) Replace keys that ends with any of the attributes before.
-  t:
+- t:
     - {before: x0, after: a0}
     - {before: x1, after: a1}
   r: "{{ l | community.general.replace_keys(target=t, matching_parameter='ends_with') }}"
 
   # 4) Replace keys that match any regex of the attributes before.
-  t:
+- t:
     - {before: "^.*0_x.*$", after: a0}
     - {before: "^.*1_x.*$", after: a1}
   r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}"
 
   # The results of above examples 1-4 are all the same.
-  r:
+- r:
     - {a0: A0, a1: B0, k2_x2: [C0], k3_x3: foo}
     - {a0: A1, a1: B1, k2_x2: [C1], k3_x3: bar}
 
   # 5) If more keys match the same attribute before the last one will be used.
-  t:
+- t:
     - {before: "^.*_x.*$", after: X}
   r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}"
 
   # gives
 
-  r:
+- r:
     - X: foo
     - X: bar
 
   # 6) If there are items with equal attribute before the first one will be used.
-  t:
+- t:
     - {before: "^.*_x.*$", after: X}
     - {before: "^.*_x.*$", after: Y}
   r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}"
 
   # gives
 
-  r:
+- r:
     - X: foo
     - X: bar
 
   # 7) If there are more matches for a key the first one will be used.
-  l:
+- l:
     - {aaa1: A, bbb1: B, ccc1: C}
     - {aaa2: D, bbb2: E, ccc2: F}
-  t:
+- t:
     - {before: a, after: X}
     - {before: aa, after: Y}
   r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}"
 
   # gives
 
-  r:
+- r:
     - {X: A, bbb1: B, ccc1: C}
     - {X: D, bbb2: E, ccc2: F}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: The list of dictionaries with replaced keys.
+  description: The list of dictionaries with replaced keys.
-    type: list
+  type: list
-    elements: dictionary
+  elements: dictionary
-'''
+"""
 
 from ansible_collections.community.general.plugins.plugin_utils.keys_filter import (
     _keys_filter_params,

plugins/filter/reveal_ansible_type.py

@@ -6,116 +6,116 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    name: reveal_ansible_type
+name: reveal_ansible_type
-    short_description: Return input type
+short_description: Return input type
-    version_added: "9.2.0"
+version_added: "9.2.0"
-    author: Vladimir Botka (@vbotka)
+author: Vladimir Botka (@vbotka)
-    description: This filter returns input type.
+description: This filter returns input type.
-    options:
+options:
-      _input:
+  _input:
-        description: Input data.
+    description: Input data.
-        type: raw
+    type: raw
-        required: true
+    required: true
-      alias:
+  alias:
-        description: Data type aliases.
+    description: Data type aliases.
-        default: {}
+    default: {}
-        type: dictionary
+    type: dictionary
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 # Substitution converts str to AnsibleUnicode
 # -------------------------------------------
 
 # String. AnsibleUnicode.
-data: "abc"
+- data: "abc"
-result: '{{ data | community.general.reveal_ansible_type }}'
+  result: '{{ data | community.general.reveal_ansible_type }}'
 # result => AnsibleUnicode
 
 # String. AnsibleUnicode alias str.
-alias: {"AnsibleUnicode": "str"}
+- alias: {"AnsibleUnicode": "str"}
-data: "abc"
+  data: "abc"
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+  result: '{{ data | community.general.reveal_ansible_type(alias) }}'
 # result => str
 
 # List. All items are AnsibleUnicode.
-data: ["a", "b", "c"]
+- data: ["a", "b", "c"]
-result: '{{ data | community.general.reveal_ansible_type }}'
+  result: '{{ data | community.general.reveal_ansible_type }}'
 # result => list[AnsibleUnicode]
 
 # Dictionary. All keys are AnsibleUnicode. All values are AnsibleUnicode.
-data: {"a": "foo", "b": "bar", "c": "baz"}
+- data: {"a": "foo", "b": "bar", "c": "baz"}
-result: '{{ data | community.general.reveal_ansible_type }}'
+  result: '{{ data | community.general.reveal_ansible_type }}'
 # result => dict[AnsibleUnicode, AnsibleUnicode]
 
 # No substitution and no alias. Type of strings is str
 # ----------------------------------------------------
 
 # String
-result: '{{ "abc" | community.general.reveal_ansible_type }}'
+- result: '{{ "abc" | community.general.reveal_ansible_type }}'
 # result => str
 
 # Integer
-result: '{{ 123 | community.general.reveal_ansible_type }}'
+- result: '{{ 123 | community.general.reveal_ansible_type }}'
 # result => int
 
 # Float
-result: '{{ 123.45 | community.general.reveal_ansible_type }}'
+- result: '{{ 123.45 | community.general.reveal_ansible_type }}'
 # result => float
 
 # Boolean
-result: '{{ true | community.general.reveal_ansible_type }}'
+- result: '{{ true | community.general.reveal_ansible_type }}'
 # result => bool
 
 # List. All items are strings.
-result: '{{ ["a", "b", "c"] | community.general.reveal_ansible_type }}'
+- result: '{{ ["a", "b", "c"] | community.general.reveal_ansible_type }}'
 # result => list[str]
 
 # List of dictionaries.
-result: '{{ [{"a": 1}, {"b": 2}] | community.general.reveal_ansible_type }}'
+- result: '{{ [{"a": 1}, {"b": 2}] | community.general.reveal_ansible_type }}'
 # result => list[dict]
 
 # Dictionary. All keys are strings. All values are integers.
-result: '{{ {"a": 1} | community.general.reveal_ansible_type }}'
+- result: '{{ {"a": 1} | community.general.reveal_ansible_type }}'
 # result => dict[str, int]
 
 # Dictionary. All keys are strings. All values are integers.
-result: '{{ {"a": 1, "b": 2} | community.general.reveal_ansible_type }}'
+- result: '{{ {"a": 1, "b": 2} | community.general.reveal_ansible_type }}'
 # result => dict[str, int]
 
 # Type of strings is AnsibleUnicode or str
 # ----------------------------------------
 
 # Dictionary. The keys are integers or strings. All values are strings.
-alias: {"AnsibleUnicode": "str"}
+- alias: {"AnsibleUnicode": "str"}
-data: {1: 'a', 'b': 'b'}
+  data: {1: 'a', 'b': 'b'}
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+  result: '{{ data | community.general.reveal_ansible_type(alias) }}'
 # result => dict[int|str, str]
 
 # Dictionary. All keys are integers. All values are keys.
-alias: {"AnsibleUnicode": "str"}
+- alias: {"AnsibleUnicode": "str"}
-data: {1: 'a', 2: 'b'}
+  data: {1: 'a', 2: 'b'}
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+  result: '{{ data | community.general.reveal_ansible_type(alias) }}'
 # result => dict[int, str]
 
 # Dictionary. All keys are strings. Multiple types values.
-alias: {"AnsibleUnicode": "str"}
+- alias: {"AnsibleUnicode": "str"}
-data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': True, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}}
+  data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': true, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}}
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+  result: '{{ data | community.general.reveal_ansible_type(alias) }}'
 # result => dict[str, bool|dict|float|int|list|str]
 
 # List. Multiple types items.
-alias: {"AnsibleUnicode": "str"}
+- alias: {"AnsibleUnicode": "str"}
-data: [1, 2, 1.1, 'abc', True, ['x', 'y', 'z'], {'x': 1, 'y': 2}]
+  data: [1, 2, 1.1, 'abc', true, ['x', 'y', 'z'], {'x': 1, 'y': 2}]
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+  result: '{{ data | community.general.reveal_ansible_type(alias) }}'
 # result => list[bool|dict|float|int|list|str]
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: Type of the data.
+  description: Type of the data.
-    type: str
+  type: str
-'''
+"""
 
 from ansible_collections.community.general.plugins.plugin_utils.ansible_type import _ansible_type
 

plugins/filter/to_ini.py

@@ -6,34 +6,34 @@
 
 from __future__ import absolute_import, division, print_function
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
-  name: to_ini
+name: to_ini
-  short_description: Converts a dictionary to the INI file format
+short_description: Converts a dictionary to the INI file format
-  version_added: 8.2.0
+version_added: 8.2.0
-  author: Steffen Scheib (@sscheib)
+author: Steffen Scheib (@sscheib)
-  description:
+description:
-    - Converts a dictionary to the INI file format.
+  - Converts a dictionary to the INI file format.
-  options:
+options:
-    _input:
+  _input:
-      description: The dictionary that should be converted to the INI format.
+    description: The dictionary that should be converted to the INI format.
-      type: dictionary
+    type: dictionary
-      required: true
+    required: true
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
-  - name: Define a dictionary
+- name: Define a dictionary
-    ansible.builtin.set_fact:
+  ansible.builtin.set_fact:
-      my_dict:
+    my_dict:
-        section_name:
+      section_name:
-          key_name: 'key value'
+        key_name: 'key value'
 
-        another_section:
+      another_section:
-          connection: 'ssh'
+        connection: 'ssh'
 
-  - name: Write dictionary to INI file
+- name: Write dictionary to INI file
-    ansible.builtin.copy:
+  ansible.builtin.copy:
-      dest: /tmp/test.ini
+    dest: /tmp/test.ini
-      content: '{{ my_dict | community.general.to_ini }}'
+    content: '{{ my_dict | community.general.to_ini }}'
 
   # /tmp/test.ini will look like this:
   # [section_name]
@@ -41,13 +41,13 @@ EXAMPLES = r'''
   #
   # [another_section]
   # connection = ssh
-'''
+"""
 
-RETURN = r'''
+RETURN = r"""
-  _value:
+_value:
-    description: A string formatted as INI file.
+  description: A string formatted as INI file.
-    type: string
+  type: string
-'''
+"""
 
 
 __metaclass__ = type

plugins/filter/unicode_normalize.py

@@ -7,45 +7,45 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: unicode_normalize
+name: unicode_normalize
-  short_description: Normalizes unicode strings to facilitate comparison of characters with normalized forms
+short_description: Normalizes unicode strings to facilitate comparison of characters with normalized forms
-  version_added: 3.7.0
+version_added: 3.7.0
-  author: Andrew Pantuso (@Ajpantuso)
+author: Andrew Pantuso (@Ajpantuso)
-  description:
+description:
-    - Normalizes unicode strings to facilitate comparison of characters with normalized forms.
+  - Normalizes unicode strings to facilitate comparison of characters with normalized forms.
-  positional: form
+positional: form
-  options:
+options:
-    _input:
+  _input:
-      description: A unicode string.
+    description: A unicode string.
-      type: string
+    type: string
-      required: true
+    required: true
-    form:
+  form:
-      description:
+    description:
-        - The normal form to use.
+      - The normal form to use.
-        - See U(https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize) for details.
+      - See U(https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize) for details.
-      type: string
+    type: string
-      default: NFC
+    default: NFC
-      choices:
+    choices:
-        - NFC
+      - NFC
-        - NFD
+      - NFD
-        - NFKC
+      - NFKC
-        - NFKD
+      - NFKD
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Normalize unicode string
   ansible.builtin.set_fact:
     dictionary: "{{ 'ä' | community.general.unicode_normalize('NFKD') }}"
     # The resulting string has length 2: one letter is 'a', the other
     # the diacritic combiner.
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: The normalized unicode string of the specified normal form.
+  description: The normalized unicode string of the specified normal form.
-    type: string
+  type: string
-'''
+"""
 
 from unicodedata import normalize
 

plugins/filter/version_sort.py

@@ -6,34 +6,34 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: version_sort
+name: version_sort
-  short_description: Sort a list according to version order instead of pure alphabetical one
+short_description: Sort a list according to version order instead of pure alphabetical one
-  version_added: 2.2.0
+version_added: 2.2.0
-  author: Eric L. (@ericzolf)
+author: Eric L. (@ericzolf)
-  description:
+description:
-    - Sort a list according to version order instead of pure alphabetical one.
+  - Sort a list according to version order instead of pure alphabetical one.
-  options:
+options:
-    _input:
+  _input:
-      description: A list of strings to sort.
+    description: A list of strings to sort.
-      type: list
+    type: list
-      elements: string
+    elements: string
-      required: true
+    required: true
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Convert list of tuples into dictionary
   ansible.builtin.set_fact:
     dictionary: "{{ ['2.1', '2.10', '2.9'] | community.general.version_sort }}"
     # Result is ['2.1', '2.9', '2.10']
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: The list of strings sorted by version.
+  description: The list of strings sorted by version.
-    type: list
+  type: list
-    elements: string
+  elements: string
-'''
+"""
 
 from ansible_collections.community.general.plugins.module_utils.version import LooseVersion