[stable-4] Move in-plugin docs to sidecar for filters not named like the filename that contain them (#4626) (#4631)

* Move in-plugin docs to sidecar for filters not named like the filename that contain them.

* Update BOTMETA.

(cherry picked from commit d1877e1915)

.github/BOTMETA.yml

@@ -126,6 +126,8 @@ files:
     maintainers: Ajpantuso
   $filters/groupby.py:
     maintainers: felixfontein
+  $filters/groupby_as_dict.yml:
+    maintainers: felixfontein
   $filters/hashids.py:
     maintainers: Ajpantuso
   $filters/hashids_decode.yml:
@@ -137,6 +139,8 @@ files:
   $filters/json_query.py: {}
   $filters/list.py:
     maintainers: vbotka
+  $filters/lists_mergeby.yml:
+    maintainers: vbotka
   $filters/path_join_shim.py:
     maintainers: felixfontein
   $filters/random_mac.py: {}

plugins/filter/groupby.py

@@ -5,52 +5,6 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
-  name: groupby_as_dict
-  short_description: Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute
-  version_added: 3.1.0
-  author: Felix Fontein (@felixfontein)
-  description:
-    - Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute.
-  positional: attribute
-  options:
-    _input:
-      description: A list of dictionaries
-      type: list
-      elements: dictionary
-      required: true
-    attribute:
-      description: The attribute to use as the key.
-      type: str
-      required: true
-'''
-
-EXAMPLES = '''
-- name: Arrange a list of dictionaries as a dictionary of dictionaries
-  ansible.builtin.debug:
-    msg: "{{ sequence | community.general.groupby_as_dict('key') }}"
-  vars:
-    sequence:
-      - key: value
-        foo: bar
-      - key: other_value
-        baz: bar
-  # Produces the following nested structure:
-  #
-  #  value:
-  #    key: value
-  #    foo: bar
-  #  other_value:
-  #    key: other_value
-  #    baz: bar
-'''
-
-RETURN = '''
-  _value:
-    description: A dictionary containing the dictionaries from the list as values.
-    type: dictionary
-'''
-
 from ansible.errors import AnsibleFilterError
 from ansible.module_utils.common._collections_compat import Mapping, Sequence
 

plugins/filter/groupby_as_dict.yml

@@ -0,0 +1,42 @@
+DOCUMENTATION:
+  name: groupby_as_dict
+  short_description: Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute
+  version_added: 3.1.0
+  author: Felix Fontein (@felixfontein)
+  description:
+    - Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute.
+  positional: attribute
+  options:
+    _input:
+      description: A list of dictionaries
+      type: list
+      elements: dictionary
+      required: true
+    attribute:
+      description: The attribute to use as the key.
+      type: str
+      required: true
+
+EXAMPLES: |
+  - name: Arrange a list of dictionaries as a dictionary of dictionaries
+    ansible.builtin.debug:
+      msg: "{{ sequence | community.general.groupby_as_dict('key') }}"
+    vars:
+      sequence:
+        - key: value
+          foo: bar
+        - key: other_value
+          baz: bar
+    # Produces the following nested structure:
+    #
+    #  value:
+    #    key: value
+    #    foo: bar
+    #  other_value:
+    #    key: other_value
+    #    baz: bar
+
+RETURN:
+  _value:
+    description: A dictionary containing the dictionaries from the list as values.
+    type: dictionary

plugins/filter/list.py

@@ -5,72 +5,6 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
-  name: lists_mergeby
-  short_description: Merge two lists of dictionaries by a given attribute
-  version_added: 2.0.0
-  author: Vladimir Botka (@vbotka)
-  description:
-    - Merge two lists by attribute I(index).
-  positional: another_list, index
-  options:
-    _input:
-      description: A list of dictionaries.
-      type: list
-      elements: dictionary
-      required: true
-    another_list:
-      description: Another list of dictionaries.
-      type: list
-      elements: dictionary
-      required: true
-    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
-'''
-
-EXAMPLES = '''
-- name: Merge two lists
-  ansible.builtin.debug:
-    msg: >-
-      {{ list1 | community.general.lists_mergeby(list2, 'index') }}"
-  vars:
-    list1:
-      - index: a
-        value: 123
-      - index: b
-        value: 42
-    list2:
-      - index: a
-        foo: bar
-      - index: c
-        foo: baz
-  # Produces the following list of dictionaries:
-  #   {
-  #     "index": "a",
-  #     "foo": "bar",
-  #     "value": 123
-  #   },
-  #   {
-  #     "index": "b",
-  #     "value": 42
-  #   },
-  #   {
-  #     "index": "c",
-  #     "foo": "baz"
-  #   }
-'''
-
-RETURN = '''
-  _value:
-    description: The merged list.
-    type: list
-    elements: dictionary
-'''
-
 from ansible.errors import AnsibleError, AnsibleFilterError
 from ansible.module_utils.six import string_types
 from ansible.module_utils.common._collections_compat import Mapping, Sequence

plugins/filter/lists_mergeby.yml

@@ -0,0 +1,62 @@
+DOCUMENTATION:
+  name: lists_mergeby
+  short_description: Merge two lists of dictionaries by a given attribute
+  version_added: 2.0.0
+  author: Vladimir Botka (@vbotka)
+  description:
+    - Merge two lists by attribute I(index).
+  positional: another_list, index
+  options:
+    _input:
+      description: A list of dictionaries.
+      type: list
+      elements: dictionary
+      required: true
+    another_list:
+      description: Another list of dictionaries.
+      type: list
+      elements: dictionary
+      required: true
+    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
+
+EXAMPLES: |
+  - name: Merge two lists
+    ansible.builtin.debug:
+      msg: >-
+        {{ list1 | community.general.lists_mergeby(list2, 'index') }}"
+    vars:
+      list1:
+        - index: a
+          value: 123
+        - index: b
+          value: 42
+      list2:
+        - index: a
+          foo: bar
+        - index: c
+          foo: baz
+    # Produces the following list of dictionaries:
+    #   {
+    #     "index": "a",
+    #     "foo": "bar",
+    #     "value": 123
+    #   },
+    #   {
+    #     "index": "b",
+    #     "value": 42
+    #   },
+    #   {
+    #     "index": "c",
+    #     "foo": "baz"
+    #   }
+
+RETURN:
+  _value:
+    description: The merged list.
+    type: list
+    elements: dictionary