Update docs helper. Automate generation of 'Merging lists of dictiona… (#4125)

* Update docs helper. Automate generation of 'Merging lists of dictionaries'.

* Updated helper/lists_mergeby/playbook.yml, list of examples and
  templates. See playbook.yml on how to create *.out files, test
  examples and generate the REST file
  filter_guide_abstract_informations_merging_lists_of_dictionaries.rst
* Generated REST file copied to directory rst
* Simplified examples. The common lists are published only once. Only
  the expressions are published instead of the whole tasks.
* To change the content of the section 'Merging lists of dictionaries'
  update template
  filter_guide_abstract_informations_merging_lists_of_dictionaries.rst.j2
  and run the playbook.
* Deleted rst/examples/lists_mergeby. Not needed anymore.

* Update docs/docsite/helper/lists_mergeby/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst.j2

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

* Update docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst

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

docs/docsite/helper/lists_mergeby/playbook.yml

@@ -1,41 +1,59 @@
 ---
-# The following runs all examples:
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# 1) Run all examples and create example-XXX.out
+# shell> ansible-playbook playbook.yml -e examples=true
 #
-#    ANSIBLE_STDOUT_CALLBACK=community.general.yaml ansible-playbook playbook.yml -e examples=true
+# 2) Optionally, for testing, create examples_all.rst
+# shell> ansible-playbook playbook.yml -e examples_all=true
 #
-# You need to copy the YAML output of example-XXX.yml into example-XXX.out.
+# 3) Create docs REST files
+# shell> ansible-playbook playbook.yml -e merging_lists_of_dictionaries=true
 #
-# The following generates examples.rst out of the .out files:
+# Notes:
+# * Use YAML callback, e.g. set ANSIBLE_STDOUT_CALLBACK=community.general.yaml
+# * Use sphinx-view to render and review the REST files
+#   shell> sphinx-view <path_to_helper>/examples_all.rst
+# * Proofread and copy completed docs *.rst files into the directory rst.
+# * Then delete the *.rst and *.out files from this directory. Do not
+#   add *.rst and *.out in this directory to the version control.
 #
-#    ansible-playbook playbook.yml -e template=true
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# community.general/docs/docsite/helper/lists_mergeby/playbook.yml
+
 - hosts: localhost
   gather_facts: false
-  vars:
-    source_path: ../../rst/examples/lists_mergeby/
   tasks:
 
     - block:
-        - import_tasks: '{{ source_path }}example-001.yml'
+        - import_tasks: example-001.yml
           tags: t001
-        - import_tasks: '{{ source_path }}example-002.yml'
+        - import_tasks: example-002.yml
           tags: t002
-        - import_tasks: '{{ source_path }}example-003.yml'
+        - import_tasks: example-003.yml
           tags: t003
-        - import_tasks: '{{ source_path }}example-004.yml'
+        - import_tasks: example-004.yml
           tags: t004
-        - import_tasks: '{{ source_path }}example-005.yml'
+        - import_tasks: example-005.yml
           tags: t005
-        - import_tasks: '{{ source_path }}example-006.yml'
+        - import_tasks: example-006.yml
           tags: t006
-        - import_tasks: '{{ source_path }}example-007.yml'
+        - import_tasks: example-007.yml
           tags: t007
-        - import_tasks: '{{ source_path }}example-008.yml'
+        - import_tasks: example-008.yml
           tags: t008
       when: examples|d(false)|bool
 
     - block:
         - include_vars: examples.yml
         - template:
-            src: examples.rst.j2
-            dest: examples.rst
-      when: template|d(false)|bool
+            src: examples_all.rst.j2
+            dest: examples_all.rst
+      when: examples_all|d(false)|bool
+
+    - block:
+        - include_vars: examples.yml
+        - template:
+            src: filter_guide_abstract_informations_merging_lists_of_dictionaries.rst.j2
+            dest: filter_guide_abstract_informations_merging_lists_of_dictionaries.rst
+      when: merging_lists_of_dictionaries|d(false)|bool