[2.10] Docsite backport of 71973, 71975, 71980 (#71991)

* Docsite: improve user_guide/playbooks_vars_facts (#71973)

* Docsite: improve user_guide/playbooks_vars_facts

* Docsite: update user_guide/vault (#71975)

* Docsite: update user_guide/playbooks_filters (#71980)

3 files changed, 66 insertions, 52 deletions

diff --git a/docs/docsite/rst/user_guide/playbooks_filters.rst b/docs/docsite/rst/user_guide/playbooks_filters.rst
index 6976607932..f009900a5b 100644
--- a/docs/docsite/rst/user_guide/playbooks_filters.rst
+++ b/docs/docsite/rst/user_guide/playbooks_filters.rst
@@ -41,8 +41,8 @@ Making variables optional
 
 By default Ansible requires values for all variables in a templated expression. However, you can make specific variables optional. For example, you might want to use a system default for some items and control the value for others. To make a variable optional, set the default value to the special variable ``omit``::
 
-    - name: touch files with an optional mode
-      file:
+    - name: Touch files with an optional mode
+      ansible.builtin.file:
         dest: "{{ item.path }}"
         state: touch
         mode: "{{ item.mode | default(omit) }}"
@@ -55,14 +55,14 @@ By default Ansible requires values for all variables in a templated expression.
 In this example, the default mode for the files ``/tmp/foo`` and ``/tmp/bar`` is determined by the umask of the system. Ansible does not send a value for ``mode``. Only the third file, ``/tmp/baz``, receives the `mode=0444` option.
 
 .. note:: If you are "chaining" additional filters after the ``default(omit)`` filter, you should instead do something like this:
-      ``"{{ foo | default(None) | some_filter or omit }}"``. In this example, the default ``None`` (Python null) value will cause the later filters to fail, which will trigger the ``or omit`` portion of the logic. Using ``omit`` in this manner is very specific to the later filters you're chaining though, so be prepared for some trial and error if you do this.
+      ``"{{ foo | default(None) | some_filter or omit }}"``. In this example, the default ``None`` (Python null) value will cause the later filters to fail, which will trigger the ``or omit`` portion of the logic. Using ``omit`` in this manner is very specific to the later filters you are chaining though, so be prepared for some trial and error if you do this.
 
 .. _forcing_variables_to_be_defined:
 
 Defining mandatory values
 -------------------------
 
-If you configure Ansible to ignore undefined variables, you may want to define some values as mandatory. By default, Ansible fails if a variable in your playbook or command is undefined. You can configure Ansible to allow undefined variables by setting :ref:`DEFAULT_UNDEFINED_VAR_BEHAVIOR` to ``false``. In that case, you may want to require some variables to be defined. You can do with this with::
+If you configure Ansible to ignore undefined variables, you may want to define some values as mandatory. By default, Ansible fails if a variable in your playbook or command is undefined. You can configure Ansible to allow undefined variables by setting :ref:`DEFAULT_UNDEFINED_VAR_BEHAVIOR` to ``false``. In that case, you may want to require some variables to be defined. You can do this with::
 
     {{ variable | mandatory }}
 
@@ -234,10 +234,12 @@ If you are reading in some already formatted data::
 for example::
 
   tasks:
-    - shell: cat /some/path/to/file.json
+    - name: Register JSON output as a variable 
+      ansible.builtin.shell: cat /some/path/to/file.json
       register: result
 
-    - set_fact:
+    - name: Set a variable
+      ansible.builtin.set_fact:
         myvar: "{{ result.stdout | from_json }}"
 
 
@@ -266,9 +268,12 @@ The ``from_yaml_all`` filter will return a generator of parsed YAML documents.
 for example::
 
   tasks:
-    - shell: cat /some/path/to/multidoc-file.yaml
+    - name: Register a file content as a variable
+      ansible.builtin.shell: cat /some/path/to/multidoc-file.yaml
       register: result
-    - debug:
+
+    - name: Print the transformed variable
+      ansible.builtin.debug:
         msg: '{{ item }}'
       loop: '{{ result.stdout | from_yaml_all | list }}'
 
@@ -286,18 +291,18 @@ Combining items from multiple lists: zip and zip_longest
 
 To get a list combining the elements of other lists use ``zip``::
 
-    - name: give me list combo of two lists
-      debug:
+    - name: Give me list combo of two lists
+      ansible.builtin.debug:
        msg: "{{ [1,2,3,4,5] | zip(['a','b','c','d','e','f']) | list }}"
 
-    - name: give me shortest combo of two lists
-      debug:
+    - name: Give me shortest combo of two lists
+      ansible.builtin.debug:
         msg: "{{ [1,2,3] | zip(['a','b','c','d','e','f']) | list }}"
 
 To always exhaust all lists use ``zip_longest``::
 
-    - name: give me longest combo of three lists , fill with X
-      debug:
+    - name: Give me longest combo of three lists , fill with X
+      ansible.builtin.debug:
         msg: "{{ [1,2,3] | zip_longest(['a','b','c','d','e','f'], [21, 22, 23], fillvalue='X') | list }}"
 
 Similarly to the output of the ``items2dict`` filter mentioned above, these filters can be used to construct a ``dict``::
@@ -374,7 +379,7 @@ Data after applying the ``subelements`` filter::
 You can use the transformed data with ``loop`` to iterate over the same subelement for multiple objects::
 
     - name: Set authorized ssh key, extracting just that data from 'users'
-      authorized_key:
+      ansible.posix.authorized_key:
         user: "{{ item.0.name }}"
         key: "{{ lookup('file', item.1) }}"
       loop: "{{ users | subelements('authorized') }}"
@@ -633,20 +638,20 @@ permutations
 ^^^^^^^^^^^^
 To get permutations of a list::
 
-    - name: give me largest permutations (order matters)
-      debug:
+    - name: Give me largest permutations (order matters)
+      ansible.builtin.debug:
         msg: "{{ [1,2,3,4,5] | permutations | list }}"
 
-    - name: give me permutations of sets of three
-      debug:
+    - name: Give me permutations of sets of three
+      ansible.builtin.debug:
         msg: "{{ [1,2,3,4,5] | permutations(3) | list }}"
 
 combinations
 ^^^^^^^^^^^^
 Combinations always require a set size::
 
-    - name: give me combinations for sets of two
-      debug:
+    - name: Give me combinations for sets of two
+      ansible.builtin.debug:
         msg: "{{ [1,2,3,4,5] | combinations(2) | list }}"
 
 Also see the :ref:`zip_filter`
@@ -657,8 +662,8 @@ The product filter returns the `cartesian product <https://docs.python.org/3/lib
 
 For example::
 
-  - name: generate multiple hostnames
-    debug:
+  - name: Generate multiple hostnames
+    ansible.builtin.debug:
       msg: "{{ ['foo', 'bar'] | product(['com']) | map('join', '.') | join(',') }}"
 
 This would result in::
@@ -730,21 +735,21 @@ Consider this data structure::
 
 To extract all clusters from this structure, you can use the following query::
 
-    - name: "Display all cluster names"
-      debug:
+    - name: Display all cluster names
+      ansible.builtin.debug:
         var: item
       loop: "{{ domain_definition | community.general.json_query('domain.cluster[*].name') }}"
 
 To extract all server names::
 
-    - name: "Display all server names"
-      debug:
+    - name: Display all server names
+      ansible.builtin.debug:
         var: item
       loop: "{{ domain_definition | community.general.json_query('domain.server[*].name') }}"
 
 To extract ports from cluster1::
 
-    - name: "Display all ports from cluster1"
+    - ansible.builtin.name: Display all ports from cluster1
       debug:
         var: item
       loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}"
@@ -755,16 +760,16 @@ To extract ports from cluster1::
 
 To print out the ports from cluster1 in a comma separated string::
 
-    - name: "Display all ports from cluster1 as a string"
-      debug:
+    - name: Display all ports from cluster1 as a string
+      ansible.builtin.debug:
         msg: "{{ domain_definition | community.general.json_query('domain.server[?cluster==`cluster1`].port') | join(', ') }}"
 
 .. note:: In the example above, quoting literals using backticks avoids escaping quotes and maintains readability.
 
 You can use YAML `single quote escaping <https://yaml.org/spec/current.html#id2534365>`_::
 
-    - name: "Display all ports from cluster1"
-      debug:
+    - name: Display all ports from cluster1
+      ansible.builtin.debug:
         var: item
       loop: "{{ domain_definition | community.general.json_query('domain.server[?cluster==''cluster1''].port') }}"
 
@@ -772,8 +777,8 @@ You can use YAML `single quote escaping <https://yaml.org/spec/current.html#id25
 
 To get a hash map with all ports and names of a cluster::
 
-    - name: "Display all server ports and names from cluster1"
-      debug:
+    - name: Display all server ports and names from cluster1
+      ansible.builtin.debug:
         var: item
       loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}"
       vars:
@@ -1561,7 +1566,8 @@ Manipulating strings
 
 To add quotes for shell usage::
 
-    - shell: echo {{ string_value | quote }}
+    - name: Run a shell command
+      ansible.builtin.shell: echo {{ string_value | quote }}
 
 To concatenate a list into a string::
 
diff --git a/docs/docsite/rst/user_guide/playbooks_vars_facts.rst b/docs/docsite/rst/user_guide/playbooks_vars_facts.rst
index 799230073d..3828b8e3dd 100644
--- a/docs/docsite/rst/user_guide/playbooks_vars_facts.rst
+++ b/docs/docsite/rst/user_guide/playbooks_vars_facts.rst
@@ -14,13 +14,15 @@ Ansible facts
 
 Ansible facts are data related to your remote systems, including operating systems, IP addresses, attached filesystems, and more. You can access this data in the ``ansible_facts`` variable. By default, you can also access some Ansible facts as top-level variables with the ``ansible_`` prefix. You can disable this behavior using the :ref:`INJECT_FACTS_AS_VARS` setting. To see all available facts, add this task to a play::
 
-    - debug: var=ansible_facts
+    - name: Print all available facts
+      ansible.builtin.debug:
+        var: ansible_facts
 
 To see the 'raw' information as gathered, run this command at the command line::
 
-    ansible <hostname> -m setup
+    ansible <hostname> -m ansible.builtin.setup
 
-Facts include a large amount of variable data, which may look like this on Ansible 2.7:
+Facts include a large amount of variable data, which may look like this:
 
 .. code-block:: json
 
@@ -518,7 +520,7 @@ Fact caching can improve performance. If you manage thousands of hosts, you can
 Disabling facts
 ---------------
 
-By default, Ansible gathers facts at the beginning of each play. If you do not need to gather facts (for example, if you know know everything about your systems centrally), you can turn off fact gathering at the play level to improve scalability. Disabling facts may particularly improve performance in push mode with very large numbers of systems, or if you are using Ansible on experimental platforms. To disable fact gathering::
+By default, Ansible gathers facts at the beginning of each play. If you do not need to gather facts (for example, if you know everything about your systems centrally), you can turn off fact gathering at the play level to improve scalability. Disabling facts may particularly improve performance in push mode with very large numbers of systems, or if you are using Ansible on experimental platforms. To disable fact gathering::
 
     - hosts: whatever
       gather_facts: no
@@ -526,7 +528,7 @@ By default, Ansible gathers facts at the beginning of each play. If you do not n
 Adding custom facts
 -------------------
 
-The setup module in Ansible automatically discovers a standard set of facts about each host. If you want to add custom values to your facts, you can write a custom facts module, set temporary facts with a ``set_fact`` task, or provide permanent custom facts using the facts.d directory.
+The setup module in Ansible automatically discovers a standard set of facts about each host. If you want to add custom values to your facts, you can write a custom facts module, set temporary facts with a ``ansible.builtin.set_fact`` task, or provide permanent custom facts using the facts.d directory.
 
 .. _local_facts:
 
@@ -547,7 +549,7 @@ To add static facts, simply add a file with the ``.facts`` extension. For exampl
 
 The next time fact gathering runs, your facts will include a hash variable fact named ``general`` with ``asdf`` and ``bar`` as members. To validate this, run the following::
 
-    ansible <hostname> -m setup -a "filter=ansible_local"
+    ansible <hostname> -m ansible.builtin.setup -a "filter=ansible_local"
 
 And you will see your custom fact added::
 
@@ -582,14 +584,20 @@ By default, fact gathering runs once at the beginning of each play. If you creat
   - hosts: webservers
     tasks:
 
-      - name: create directory for ansible custom facts
-        file: state=directory recurse=yes path=/etc/ansible/facts.d
+      - name: Create directory for ansible custom facts
+        ansible.builtin.file:
+          state: directory
+          recurse: yes
+          path: /etc/ansible/facts.d
 
-      - name: install custom ipmi fact
-        copy: src=ipmi.fact dest=/etc/ansible/facts.d
+      - name: Install custom ipmi fact
+        ansible.builtin.copy:
+          src: ipmi.fact
+          dest: /etc/ansible/facts.d
 
-      - name: re-read facts after adding custom fact
-        setup: filter=ansible_local
+      - name: Re-read facts after adding custom fact
+        ansible.builtin.setup:
+          filter: ansible_local
 
 If you use this pattern frequently, a custom facts module would be more efficient than facts.d.
 
@@ -664,9 +672,9 @@ Ansible version
 To adapt playbook behavior to different versions of Ansible, you can use the variable ``ansible_version``, which has the following structure::
 
     "ansible_version": {
-        "full": "2.0.0.2",
+        "full": "2.10.1",
         "major": 2,
-        "minor": 0,
-        "revision": 0,
-        "string": "2.0.0.2"
+        "minor": 10,
+        "revision": 1,
+        "string": "2.10.1"
     }
diff --git a/docs/docsite/rst/user_guide/vault.rst b/docs/docsite/rst/user_guide/vault.rst
index 0f5d035b71..d84aefec48 100644
--- a/docs/docsite/rst/user_guide/vault.rst
+++ b/docs/docsite/rst/user_guide/vault.rst
@@ -264,7 +264,7 @@ You can view the original value of an encrypted variable using the debug module.
 
 .. code-block:: console
 
-   ansible localhost -m debug -a var="new_user_password" -e "@vars.yml" --vault-id dev@a_password_file
+   ansible localhost -m ansible.builtin.debug -a var="new_user_password" -e "@vars.yml" --vault-id dev@a_password_file
 
    localhost | SUCCESS => {
        "new_user_password": "hunter2"