Feature. Add chapter 'Lists of dictionaries' to docsite (#8482)

* Feature. Add chapter 'Lists of dictionaries'

* Fix copyright and licensing.

* Add maintainers for docsite chapter 'Lists of dictionaries'.

* Generate docs keep_keys and remove_keys

* Update integration tests of keep_keys and remove_keys
* Update docs helpers of keep_keys and remove_keys

* Fix copyright and licensing.

* Fix remove license from templates. Cleanup.

* Add docs helper replace_keys

* Update integration test filter_replace_keys
* Generate and update:
  filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst

* Formatting improved.

* Fix results Jinja quotation marks.

* Update docs/docsite/helper/keep_keys/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst.j2

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

* Update docs/docsite/helper/keep_keys/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst.j2

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

* Fix references.

* Updated helpers.

* Fix licenses. Simplified templates.

* Fix licenses.

* Fix README.

---------

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

docs/docsite/helper/replace_keys/README.md

@@ -0,0 +1,61 @@
+<!--
+Copyright (c) Ansible Project
+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
+-->
+
+# Docs helper. Create RST file.
+
+The playbook `playbook.yml` writes a RST file that can be used in
+docs/docsite/rst. The usage of this helper is recommended but not
+mandatory. You can stop reading here and update the RST file manually
+if you don't want to use this helper.
+
+## Run the playbook
+
+If you want to generate the RST file by this helper fit the variables
+in the playbook and the template to your needs. Then, run the play
+
+```sh
+shell> ansible-playbook playbook.yml
+```
+
+## Copy RST to docs/docsite/rst
+
+Copy the RST file to `docs/docsite/rst` and remove it from this
+directory.
+
+## Update the checksums
+
+Substitute the variables and run the below commands
+
+```sh
+shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
+shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
+```
+
+## Playbook explained
+
+The playbook includes the variable *tests* from the integration tests
+and creates the RST file from the template. The playbook will
+terminate if:
+
+* The file with the variable *tests* was changed
+* The RST file was changed
+
+This means that this helper is probably not up to date.
+
+### The file with the variable *tests* was changed
+
+This means that somebody updated the integration tests. Review the
+changes and update the template if needed. Update the checksum to pass
+the integrity test. The playbook message provides you with the
+command.
+
+### The RST file was changed
+
+This means that somebody updated the RST file manually. Review the
+changes and update the template. Update the checksum to pass the
+integrity test. The playbook message provides you with the
+command. Make sure that the updated template will create identical RST
+file. Only then apply your changes.

docs/docsite/helper/replace_keys/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst.j2

@@ -0,0 +1,110 @@
+..
+  Copyright (c) Ansible Project
+  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
+
+replace_keys
+""""""""""""
+
+Use the filter :ansplugin:`community.general.replace_keys#filter` if you have a list of dictionaries and want to replace certain keys.
+
+.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ansplugin:`the documentation for the community.general.yaml callback plugin <community.general.yaml#callback>`.
+
+
+Let us use the below list in the following examples:
+
+.. code-block:: yaml
+
+   input:
+     {{ tests.0.input | to_yaml(indent=2) | indent(5) }}
+
+{% for i in tests[0:1]|subelements('group') %}
+* {{ i.1.d }}
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-3
+
+   target:
+     {{ i.1.tt | to_yaml(indent=2) | indent(5) }}
+   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
+
+{% endfor %}
+
+gives
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     {{ tests.0.result | to_yaml(indent=2) | indent(5) }}
+ 
+.. versionadded:: 9.1.0
+
+* The results of the below examples 1-3 are all the same:
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     {{ tests.1.result | to_yaml(indent=2) | indent(5) }}
+
+{% for i in tests[1:2]|subelements('group') %}
+{{ loop.index }}. {{ i.1.d }}
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-4
+
+   mp: {{ i.1.mp }}
+   target:
+     {{ i.1.tt | to_yaml(indent=2) | indent(5) }}
+   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
+
+{% endfor %}
+
+* The results of the below examples 4-5 are the same:
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     {{ tests.2.result | to_yaml(indent=2) | indent(5) }}
+
+{% for i in tests[2:3]|subelements('group') %}
+{{ loop.index + 3 }}. {{ i.1.d }}
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-3
+
+   mp: {{ i.1.mp }}
+   target:
+     {{ i.1.tt | to_yaml(indent=2) | indent(5) }}
+   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
+
+{% endfor %}
+
+{% for i in tests[3:4]|subelements('group') %}
+{{ loop.index + 5 }}. {{ i.1.d }}
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   input:
+     {{ i.0.input | to_yaml(indent=2) | indent(5) }}
+
+.. code-block:: yaml+jinja
+   :emphasize-lines: 1-4
+
+   mp: {{ i.1.mp }}
+   target:
+     {{ i.1.tt | to_yaml(indent=2) | indent(5) }}
+   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
+
+gives
+
+.. code-block:: yaml
+   :emphasize-lines: 1-
+
+   result:
+     {{ i.0.result | to_yaml(indent=2) | indent(5) }}
+
+{% endfor %}

docs/docsite/helper/replace_keys/playbook.yml

@@ -0,0 +1,79 @@
+---
+# Copyright (c) Ansible Project
+# 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
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Create docs REST files
+# shell> ansible-playbook playbook.yml
+#
+# Proofread and copy created *.rst file into the directory
+# docs/docsite/rst. Do not add *.rst in this directory to the version
+# control.
+#
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# community.general/docs/docsite/helper/replace_keys/playbook.yml
+
+- name: Create RST file for docs/docsite/rst
+  hosts: localhost
+  gather_facts: false
+
+  vars:
+
+    plugin: replace_keys
+    plugin_type: filter
+    docs_path:
+      - filter_guide
+      - abstract_informations
+      - lists_of_dictionaries
+
+    file_base: "{{ (docs_path + [plugin]) | join('-') }}"
+    file_rst: ../../rst/{{ file_base }}.rst
+    file_sha1: "{{ plugin }}.rst.sha1"
+
+    target: "../../../../tests/integration/targets/{{ plugin_type }}_{{ plugin }}"
+    target_vars: "{{ target }}/vars/main/tests.yml"
+    target_sha1: tests.yml.sha1
+
+  tasks:
+
+    - name: Test integrity tests.yml
+      when:
+        - integrity | d(true) | bool
+        - lookup('file', target_sha1) != lookup('pipe', 'sha1sum ' ~  target_vars)
+      block:
+
+        - name: Changed tests.yml
+          ansible.builtin.debug:
+            msg: |
+              Changed {{ target_vars }}
+              Review the changes and update {{ target_sha1 }}
+              shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
+
+        - name: Changed tests.yml end host
+          ansible.builtin.meta: end_play
+
+    - name: Test integrity RST file
+      when:
+        - integrity | d(true) | bool
+        - lookup('file', file_sha1) != lookup('pipe', 'sha1sum ' ~ file_rst)
+      block:
+
+        - name: Changed RST file
+          ansible.builtin.debug:
+            msg: |
+              Changed {{ file_rst }}
+              Review the changes and update {{ file_sha1 }}
+              shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
+
+        - name: Changed RST file end host
+          ansible.builtin.meta: end_play
+
+    - name: Include target vars
+      include_vars:
+        file: "{{ target_vars }}"
+
+    - name: Create RST file
+      ansible.builtin.template:
+        src: "{{ file_base }}.rst.j2"
+        dest: "{{ file_base }}.rst"

docs/docsite/helper/replace_keys/replace_keys.rst.sha1

@@ -0,0 +1 @@
+403f23c02ac02b1c3b611cb14f9b3ba59dc3f587  ../../rst/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst

docs/docsite/helper/replace_keys/replace_keys.rst.sha1.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+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

docs/docsite/helper/replace_keys/tests.yml.sha1

@@ -0,0 +1 @@
+2e54f3528c95cca746d5748f1ed7ada56ad0890e  ../../../../tests/integration/targets/filter_replace_keys/vars/main/tests.yml

docs/docsite/helper/replace_keys/tests.yml.sha1.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+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