Add docs for the filter reveal_ansible_type and the test ansible_type.

.github/BOTMETA.yml

@@ -1460,6 +1460,10 @@ files:
     maintainers: vbotka
   docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst:
     maintainers: vbotka
+  docs/docsite/rst/filter_guide-abstract_informations-types.rst:
+    maintainers: vbotka
+  docs/docsite/rst/filter_guide-abstract_informations-types-reveal_ansible_type.rst:
+    maintainers: vbotka
   docs/docsite/rst/filter_guide_conversions.rst:
     maintainers: Ajpantuso kellyjonbrazil
   docs/docsite/rst/filter_guide_creating_identifiers.rst:
@@ -1488,6 +1492,10 @@ files:
     maintainers: russoz
   docs/docsite/rst/test_guide.rst:
     maintainers: felixfontein
+  docs/docsite/rst/test_guide-ansible_type.rst:
+    maintainers: vbotka
+  docs/docsite/rst/test_guide-feature_tests.rst:
+    maintainers: felixfontein
 #########################
   tests/:
     labels: tests

docs/docsite/helper/ansible_type/README.md

@@ -0,0 +1,51 @@
+<!--
+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,
+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 command
+
+```sh
+shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
+```
+
+## Playbook explained
+
+The playbook includes the variable *tests* and creates the RST file
+from the template. The playbook will terminate if the RST file was
+changed manually. Review the changes and update the template and
+variable *tests* if needed. Update the checksum to pass the integrity
+test. The playbook message provides you with the command. Make sure
+that the updated template nd vars create identical RST file. Only then
+apply your changes.
+
+## Optionally create integration test tasks and plugin examples
+
+```sh
+shell> ansible-playbook playbook.yml -e enable_tasks=true
+shell> ansible-playbook playbook.yml -e enable_examples=true
+```

docs/docsite/helper/ansible_type/ansible_type.rst.sha1

@@ -0,0 +1 @@
+6ca4b820eb61d71c2796046550b06ab9b8e444c5  ../../rst/test_guide-ansible_type.rst

docs/docsite/helper/ansible_type/ansible_type.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/ansible_type/playbook.yml

@@ -0,0 +1,74 @@
+---
+# 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. Optionally create integration tasks and
+# plugin examples.
+#
+# 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/ansible_type/playbook.yml
+
+- name: Create RST file for docs/docsite/rst
+  hosts: localhost
+  gather_facts: false
+
+  vars:
+
+    plugin: ansible_type
+    docs_path:
+      - test_guide
+
+    file_base: "{{ (docs_path + [plugin]) | join('-') }}"
+    file_rst: ../../rst/{{ file_base }}.rst
+    file_sha1: "{{ plugin }}.rst.sha1"
+
+    start: "{{ '{{' }}"
+    stop: "{{ '}}' }}"
+
+  tasks:
+
+    - 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: vars/main/tests.yml
+
+    - name: Create RST file
+      ansible.builtin.template:
+        src: "{{ file_base }}.rst.j2"
+        dest: "{{ file_base }}.rst"
+      when: enable_rst | d(true) | bool
+
+    - name: Create plugin examples
+      ansible.builtin.template:
+        src: examples.yml.j2
+        dest: examples.yml
+      when: enable_examples | d(false) | bool
+
+    - name: Create integration tasks
+      ansible.builtin.template:
+        src: tasks.yml.j2
+        dest: tasks.yml
+      when: enable_tasks | d(false) | bool

docs/docsite/helper/ansible_type/templates/examples.yml.j2

@@ -0,0 +1,67 @@
+# 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
+
+# Substitution converts str to AnsibleUnicode
+# -------------------------------------------
+{% for i in (0, 1, 2, 3) %}
+
+# {{ tests[i].d }}
+{% if tests[i].alias is defined %}
+alias: {{ tests[i].alias | to_json }}
+dtype: {{ tests[i].r }}
+data: {{ tests[i].i | to_json }}
+result: '{{ start }} data is community.general.ansible_type(dtype, alias) {{ stop }}'
+# result => true
+{% else %}
+dtype: {{ tests[i].r }}
+data: {{ tests[i].i | to_json }}
+result: '{{ start }} data is community.general.ansible_type(dtype) {{ stop }}'
+# result => true
+{% endif %}
+{% endfor %}
+
+# No substitution and no alias. Type of strings is str
+# ----------------------------------------------------
+{% for test in tests.4.group %}
+
+# {{ test.d }}
+dtype: {{ test.r }}
+result: '{{ start }} {{ test.i | to_json }} is community.general.ansible_type(dtype) {{ stop }}'
+# result => true
+{% endfor %}
+
+# Type of strings is AnsibleUnicode or str
+# ----------------------------------------
+{% for test in tests.5.group %}
+
+# {{ test.d }}
+alias: {{ tests.5.alias | to_json }}
+dtype: {{ test.r }}
+data: {{ test.i }}
+result: '{{ start }} data is community.general.ansible_type(dtype, alias) {{ stop }}'
+# result => true
+{% endfor %}
+
+# Option dtype is list
+# --------------------
+{% for test in tests.6.group %}
+
+# {{ test.d }}
+dtype: {{ test.r }}
+data: {{ test.i }}
+result: '{{ start }} data is community.general.ansible_type(dtype) {{ stop }}'
+# result => true
+{% endfor %}
+
+# Multiple alias
+# --------------
+{% for test in tests.7.group %}
+
+# {{ test.d }}
+alias: {{ tests.7.alias | to_json }}
+dtype: {{ test.r }}
+data: {{ test.i }}
+result: '{{ start }} data is community.general.ansible_type(dtype, alias) {{ stop }}'
+# result => true
+{% endfor %}

docs/docsite/helper/ansible_type/templates/tasks.yml.j2

@@ -0,0 +1,96 @@
+# 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
+
+# Substitution converts str to AnsibleUnicode
+# -------------------------------------------
+{% for i in (0, 1, 2, 3) %}
+
+- name: {{ tests[i].d }}
+  assert:
+{% if tests[i].alias is defined %}
+    that: data is community.general.ansible_type(dtype, alias)
+    success_msg: '{{ tests[i].i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg: '{{ tests[i].i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    alias: {{ tests[i].alias | to_json }}
+    data: {{ tests[i].i | to_json }}
+    result: '{{ start }} data | community.general.reveal_ansible_type(alias) {{ stop }}'
+    dtype: '{{ tests[i].r }}'
+{% else %}
+    that: data is community.general.ansible_type(dtype)
+    success_msg: '{{ tests[i].i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg: '{{ tests[i].i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    data: {{ tests[i].i | to_json }}
+    result: '{{ start }} data | community.general.reveal_ansible_type {{ stop }}'
+    dtype: '{{ tests[i].r }}'
+{% endif %}
+{% endfor %}
+
+# No substitution and no alias. Type of strings is str
+# ----------------------------------------------------
+{% for test in tests.4.group %}
+
+- name: {{ test.d }}
+  assert:
+    that: '{{ test.i | to_json }} is community.general.ansible_type(dtype)'
+    success_msg: '{{ test.i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg:  '{{ test.i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    result: '{{ start }} {{ test.i | to_json }} | community.general.reveal_ansible_type {{ stop }}'
+    dtype: {{ test.r }}
+{% endfor %}
+
+# Type of strings is AnsibleUnicode or str
+# ----------------------------------------
+{% for test in tests.5.group %}
+
+- name: {{ test.d }}
+  assert:
+    that: data is community.general.ansible_type(dtype, alias)
+    success_msg: '{{ test.i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg: '{{ test.i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    alias: {{ tests.5.alias | to_json }}
+    data: {{ test.i }}
+    result: '{{ start }} data | community.general.reveal_ansible_type(alias) {{ stop }}'
+    dtype: {{ test.r }}
+{% endfor %}
+
+# Option dtype is list
+# --------------------
+{% for test in tests.6.group %}
+
+- name: {{ test.d }}
+  assert:
+    that: data is community.general.ansible_type(dtype)
+    success_msg: '{{ test.i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg: '{{ test.i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    data: {{ test.i }}
+    result: '{{ start }} data | community.general.reveal_ansible_type {{ stop }}'
+    dtype: {{ test.r }}
+{% endfor %}
+
+# Multiple alias
+# --------------
+{% for test in tests.7.group %}
+
+- name: {{ test.d }}
+  assert:
+    that: data is community.general.ansible_type(dtype, alias)
+    success_msg: '{{ test.i | to_json }} is {{ start }} dtype {{ stop }}'
+    fail_msg: '{{ test.i | to_json }} is {{ start }} result {{ stop }}'
+    quiet: '{{ start }} quiet_test | d(true) | bool {{ stop }}'
+  vars:
+    alias: {{ tests.7.alias | to_json }}
+    data: {{ test.i }}
+    result: '{{ start }} data | community.general.reveal_ansible_type(alias) {{ stop }}'
+    dtype: {{ test.r }}
+{% endfor %}