Add options to filter lists_mergeby (#4058)

* Update filter lists_mergeby #4057

* Added options 'recursive' and 'list_merge'. The functionality of the
  added options is the same as in the filter 'combine'.
* Allow the user to do [list1, list2, ...]|lists_mergeby('index')
* Use the function merge_hash from ansible.utils.vars

* Add merge_hash_wrapper to test Ansible version

* Enable Ansible 2.9 and lower versions with default options of
  lists_mergeby only.
* Non-default options of lists_mergeby trigger error in 2.9 and lower
  versions.
* Update messages and tests.

* Fix tests.

* Use LooseVersion instead of SpecifierSet.

* Update docs 'Filter Guide' section 'Merging lists of dictionaries'.

* Added changelog fragment.

* Update changelogs/fragments/4058-lists_mergeby-add-parameters.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/filter_guide.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/filter_guide.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/filter_guide.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/filter_guide.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/filter_guide.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Added examples; moved to rst/examples; fixes.

* Improve error message testing sequence.

* Removed .yamllint

* Update docs/docsite/rst/examples/lists_mergeby/example-003.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/examples/lists_mergeby/example-004.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/examples/lists_mergeby/example-005.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/examples/lists_mergeby/example-006.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/examples/lists_mergeby/example-007.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/filter_guide.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/filter_guide.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/filter_guide.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update tests/integration/targets/filter_list/tasks/lists_mergeby_default.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/examples/lists_mergeby/example-008.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Fix docs. Antsibull only copies .rst files.

* Fix examples in-line.

* Update docs/docsite/rst/filter_guide.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/examples/lists_mergeby/examples.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/examples/lists_mergeby/examples.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/examples/lists_mergeby/examples.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/examples/lists_mergeby/examples.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/examples/lists_mergeby/examples.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs/docsite/rst/examples/lists_mergeby/examples.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update docs lists_mergeby. Remove rubbish.

* Emphasized labes of examples in filter_guide.rst
* Removed temporary file examples/lists_mergeby/examples.rst
* Removed tests/integration/targets/filter_list/runme.*

* Fix docs. Description of the lists_merge options.

* Move helper files out of rst/ directory.

Co-authored-by: Felix Fontein <felix@fontein.de>

docs/docsite/rst/examples/lists_mergeby/example-003.yml

@@ -0,0 +1,28 @@
+---
+- name: Merge recursive by 'name', replace lists (default)
+  set_fact:
+    list3: "{{ [list1, list2]|
+               community.general.lists_mergeby('name',
+                                               recursive=true) }}"
+  vars:
+    list1:
+      - name: myname01
+        param01:
+          x: default_value
+          y: default_value
+          list:
+            - default_value
+      - name: myname02
+        param01: [1, 1, 2, 3]
+
+    list2:
+      - name: myname01
+        param01:
+          y: patch_value
+          z: patch_value
+          list:
+            - patch_value
+      - name: myname02
+        param01: [3, 4, 4, {key: value}]
+- debug:
+    var: list3