[2.10] Docsite backports of 71938, 71907 (#71972)

* Docsite: improve user_guide/playbooks_variables (#71938)
(cherry picked from commit c19af92be6950d214200fae2266328994194887f)

* Docsite: improve inventory-related pages (#71907)
Update docs/docsite/rst/plugins/inventory.rst
(cherry picked from commit 2fed63a9301821ff3f7dcfa6abfba576277d6e57)

3 files changed, 37 insertions, 33 deletions

diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst
index a34796bb2a..562c130374 100644
--- a/docs/docsite/rst/plugins/inventory.rst
+++ b/docs/docsite/rst/plugins/inventory.rst
@@ -7,7 +7,7 @@ Inventory Plugins
    :local:
    :depth: 2
 
-Inventory plugins allow users to point at data sources to compile the inventory of hosts that Ansible uses to target tasks, either via the ``-i /path/to/file`` and/or ``-i 'host1, host2'`` command line parameters or from other configuration sources.
+Inventory plugins allow users to point at data sources to compile the inventory of hosts that Ansible uses to target tasks, either using the ``-i /path/to/file`` and/or ``-i 'host1, host2'`` command line parameters or from other configuration sources.
 
 
 .. _enabling_inventory:
@@ -24,7 +24,7 @@ In some circumstances, for example, if the inventory plugin does not use a YAML
    [inventory]
    enable_plugins = host_list, script, auto, yaml, ini, toml
 
-If the plugin is in a collection you need to use the fully qualified name:
+If the plugin is in a collection, use the fully qualified name:
 
 .. code-block:: ini
 
@@ -37,11 +37,11 @@ If the plugin is in a collection you need to use the fully qualified name:
 Using inventory plugins
 -----------------------
 
-To use an inventory plugin you need to provide an inventory source. Most of the time this is a file containing host information or a YAML configuration file with options for the plugin. You can use the ``-i`` flag to provide inventory sources or configure a default inventory path.
+To use an inventory plugin, you must provide an inventory source. Most of the time this is a file containing host information or a YAML configuration file with options for the plugin. You can use the ``-i`` flag to provide inventory sources or configure a default inventory path.
 
 .. code-block:: bash
 
-   ansible hostname -i inventory_source -m ping
+   ansible hostname -i inventory_source -m ansible.builtin.ping
 
 To start using an inventory plugin with a YAML configuration source, create a file with the accepted filename schema documented for the plugin in question, then add ``plugin: plugin_name``. Use the fully qualified name if the plugin is in a collection.
 
@@ -62,7 +62,7 @@ After providing any required options, you can view the populated inventory with
       |  |--ec2-98-765-432-10.compute-1.amazonaws.com
       |--@ungrouped:
 
-If you are using an inventory plugin in a playbook-adjacent collection and want to test your setup with ``ansible-inventory``, you will need to use the ``--playbook-dir`` flag.
+If you are using an inventory plugin in a playbook-adjacent collection and want to test your setup with ``ansible-inventory``, use the ``--playbook-dir`` flag.
 
 Your inventory source might be a directory of inventory configuration files. The constructed inventory plugin only operates on those hosts already in inventory, so you may want the constructed inventory configuration parsed at a particular point (such as last). Ansible parses the directory recursively, alphabetically. You cannot configure the parsing approach, so name your files to make it work predictably. Inventory plugins that extend constructed features directly can work around that restriction by adding constructed options in addition to the inventory plugin options. Otherwise, you can use ``-i`` with multiple sources to impose a specific order, for example ``-i demo.aws_ec2.yml -i clouds.yml -i constructed.yml``.
 
@@ -71,7 +71,7 @@ You can create dynamic groups using host variables with the constructed ``keyed_
 .. code-block:: yaml
 
     # demo.aws_ec2.yml
-    plugin: aws_ec2
+    plugin: amazon.aws.aws_ec2
     regions:
       - us-east-1
       - us-east-2
@@ -112,7 +112,7 @@ Inventory plugins that support caching can use the general settings for the fact
 .. code-block:: yaml
 
     # demo.aws_ec2.yml
-    plugin: aws_ec2
+    plugin: amazon.aws.aws_ec2
     cache: yes
     cache_plugin: ansible.builtin.jsonfile
     cache_timeout: 7200
diff --git a/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst b/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst
index 10b4b3d2c1..69016655e4 100644
--- a/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst
+++ b/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst
@@ -10,13 +10,13 @@ Working with dynamic inventory
 
 If your Ansible inventory fluctuates over time, with hosts spinning up and shutting down in response to business demands, the static inventory solutions described in :ref:`inventory` will not serve your needs. You may need to track hosts from multiple sources: cloud providers, LDAP, `Cobbler <https://cobbler.github.io>`_, and/or enterprise CMDB systems.
 
-Ansible integrates all of these options via a dynamic external inventory system. Ansible supports two ways to connect with external inventory:  :ref:`inventory_plugins` and `inventory scripts`.
+Ansible integrates all of these options through a dynamic external inventory system. Ansible supports two ways to connect with external inventory:  :ref:`inventory_plugins` and `inventory scripts`.
 
 Inventory plugins take advantage of the most recent updates to the Ansible core code. We recommend plugins over scripts for dynamic inventory. You can :ref:`write your own plugin <developing_inventory>` to connect to additional dynamic inventory sources.
 
-You can still use inventory scripts if you choose. When we implemented inventory plugins, we ensured backwards compatibility via the script inventory plugin. The examples below illustrate how to use inventory scripts.
+You can still use inventory scripts if you choose. When we implemented inventory plugins, we ensured backwards compatibility through the script inventory plugin. The examples below illustrate how to use inventory scripts.
 
-If you would like a GUI for handling dynamic inventory, the :ref:`ansible_tower` inventory database syncs with all your dynamic inventory sources, provides web and REST access to the results, and offers a graphical inventory editor. With a database record of all of your hosts, you can correlate past event history and see which hosts have had failures on their last playbook runs.
+If you prefer a GUI for handling dynamic inventory, the :ref:`ansible_tower` inventory database syncs with all your dynamic inventory sources, provides web and REST access to the results, and offers a graphical inventory editor. With a database record of all of your hosts, you can correlate past event history and see which hosts have had failures on their last playbook runs.
 
 .. _cobbler_example:
 
@@ -53,7 +53,7 @@ Add a ``cobbler.ini`` file in ``/etc/ansible`` so Ansible knows where the Cobble
     cache_max_age = 900
 
 
-First test the script by running ``/etc/ansible/cobbler.py`` directly.   You should see some JSON data output, but it may not have anything in it just yet.
+First test the script by running ``/etc/ansible/cobbler.py`` directly. You should see some JSON data output, but it may not have anything in it just yet.
 
 Let's explore what this does.  In Cobbler, assume a scenario somewhat like the following:
 
@@ -64,9 +64,9 @@ Let's explore what this does.  In Cobbler, assume a scenario somewhat like the f
     cobbler system edit --name=foo --dns-name="foo.example.com" --mgmt-classes="atlanta" --ksmeta="c=4"
     cobbler system edit --name=bar --dns-name="bar.example.com" --mgmt-classes="atlanta" --ksmeta="c=5"
 
-In the example above, the system 'foo.example.com' are addressable by ansible directly, but are also addressable when using the group names 'webserver' or 'atlanta'.  Since Ansible uses SSH, it contacts system foo over 'foo.example.com', only, never just 'foo'.  Similarly, if you try "ansible foo" it wouldn't find the system... but "ansible 'foo*'" would, because the system DNS name starts with 'foo'.
+In the example above, the system 'foo.example.com' is addressable by ansible directly, but is also addressable when using the group names 'webserver' or 'atlanta'. Since Ansible uses SSH, it contacts system foo over 'foo.example.com', only, never just 'foo'. Similarly, if you tried "ansible foo", it would not find the system... but "ansible 'foo*'" would do, because the system DNS name starts with 'foo'.
 
-The script provides more than host and group info.  In addition, as a bonus, when the 'setup' module is run (which happens automatically when using playbooks), the variables 'a', 'b', and 'c' will all be auto-populated in the templates:
+The script provides more than host and group info. In addition, as a bonus, when the 'setup' module is run (which happens automatically when using playbooks), the variables 'a', 'b', and 'c' will all be auto-populated in the templates:
 
 .. code-block:: text
 
@@ -86,7 +86,7 @@ Which could be executed just like this:
    normal in Ansible, but variables from the external inventory script
    will override any that have the same name.
 
-So, with the template above (``motd.j2``), this would result in the following data being written to ``/etc/motd`` for system 'foo':
+So, with the template above (``motd.j2``), this results in the following data being written to ``/etc/motd`` for system 'foo':
 
 .. code-block:: text
 
@@ -98,11 +98,11 @@ And on system 'bar' (bar.example.com):
 
     Welcome, I am templated with a value of a=2, b=3, and c=5
 
-And technically, though there is no major good reason to do it, this also works too:
+And technically, though there is no major good reason to do it, this also works:
 
 .. code-block:: bash
 
-    ansible webserver -m shell -a "echo {{ a }}"
+    ansible webserver -m ansible.builtin.shell -a "echo {{ a }}"
 
 So, in other words, you can use those variables in arguments/actions as well.
 
@@ -138,7 +138,7 @@ Source an OpenStack RC file:
 
     An OpenStack RC file contains the environment variables required by the client tools to establish a connection with the cloud provider, such as the authentication URL, user name, password and region name. For more information on how to download, create or source an OpenStack RC file, please refer to `Set environment variables using the OpenStack RC file <https://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html>`_.
 
-You can confirm the file has been successfully sourced by running a simple command, such as `nova list` and ensuring it return no errors.
+You can confirm the file has been successfully sourced by running a simple command, such as `nova list` and ensuring it returns no errors.
 
 .. note::
 
@@ -154,7 +154,7 @@ Once you confirm the dynamic inventory script is working as expected, you can te
 
 .. code-block:: bash
 
-    ansible -i openstack_inventory.py all -m ping
+    ansible -i openstack_inventory.py all -m ansible.builtin.ping
 
 Implicit use of OpenStack inventory script
 ------------------------------------------
@@ -208,15 +208,15 @@ If the location given to ``-i`` in Ansible is a directory (or as so configured i
 at the same time.  When doing so, it is possible to mix both dynamic and statically managed inventory sources in the same ansible run. Instant
 hybrid cloud!
 
-In an inventory directory, executable files will be treated as dynamic inventory sources and most other files as static sources. Files which end with any of the following will be ignored:
+In an inventory directory, executable files are treated as dynamic inventory sources and most other files as static sources. Files which end with any of the following are ignored:
 
 .. code-block:: text
 
     ~, .orig, .bak, .ini, .cfg, .retry, .pyc, .pyo
 
-You can replace this list with your own selection by configuring an ``inventory_ignore_extensions`` list in ansible.cfg, or setting the :envvar:`ANSIBLE_INVENTORY_IGNORE` environment variable. The value in either case should be a comma-separated list of patterns, as shown above.
+You can replace this list with your own selection by configuring an ``inventory_ignore_extensions`` list in ``ansible.cfg``, or setting the :envvar:`ANSIBLE_INVENTORY_IGNORE` environment variable. The value in either case must be a comma-separated list of patterns, as shown above.
 
-Any ``group_vars`` and ``host_vars`` subdirectories in an inventory directory will be interpreted as expected, making inventory directories a powerful way to organize different sets of configurations. See :ref:`using_multiple_inventory_sources` for more information.
+Any ``group_vars`` and ``host_vars`` subdirectories in an inventory directory are interpreted as expected, making inventory directories a powerful way to organize different sets of configurations. See :ref:`using_multiple_inventory_sources` for more information.
 
 .. _static_groups_of_dynamic:
 
@@ -224,7 +224,7 @@ Static groups of dynamic groups
 ===============================
 
 When defining groups of groups in the static inventory file, the child groups
-must also be defined in the static inventory file, or ansible will return an
+must also be defined in the static inventory file, otherwise ansible returns an
 error. If you want to define a static group of dynamic child groups, define
 the dynamic groups as empty in the static inventory file. For example:
 
diff --git a/docs/docsite/rst/user_guide/playbooks_variables.rst b/docs/docsite/rst/user_guide/playbooks_variables.rst
index e77144dec4..eb2b58f7b0 100644
--- a/docs/docsite/rst/user_guide/playbooks_variables.rst
+++ b/docs/docsite/rst/user_guide/playbooks_variables.rst
@@ -58,7 +58,9 @@ Referencing simple variables
 
 After you define a variable, use Jinja2 syntax to reference it. Jinja2 variables use double curly braces. For example, the expression ``My amp goes to {{ max_amp_value }}`` demonstrates the most basic form of variable substitution. You can use Jinja2 syntax in playbooks. For example::
 
-    template: src=foo.cfg.j2 dest={{ remote_install_path }}/foo.cfg
+    ansible.builtin.template:
+      src: foo.cfg.j2
+      dest: '{{ remote_install_path }}/foo.cfg'
 
 In this example, the variable defines the location of a file, which can vary from one system to another.
 
@@ -150,11 +152,13 @@ You can create variables from the output of an Ansible task with the task keywor
 
      tasks:
 
-        - shell: /usr/bin/foo
+        - name: Run a shell command and register its output as a variable
+          ansible.builtin.shell: /usr/bin/foo
           register: foo_result
-          ignore_errors: True
+          ignore_errors: true
 
-        - shell: /usr/bin/bar
+        - name: Run a shell command using output of the previous task
+          ansible.builtin.shell: /usr/bin/bar
           when: foo_result.rc == 5
 
 For more examples of using registered variables in conditions on later tasks, see :ref:`playbooks_conditionals`. Registered variables may be simple variables, list variables, dictionary variables, or complex nested data structures. The documentation for each module includes a ``RETURN`` section describing the return values for that module. To see the values for a particular task, run your playbook with ``-v``.
@@ -234,8 +238,8 @@ This example shows how you can include variables defined in an external file::
 
       tasks:
 
-      - name: this is just a placeholder
-        command: /bin/echo foo
+      - name: This is just a placeholder
+        ansible.builtin.command: /bin/echo foo
 
 The contents of each variables file is a simple YAML dictionary. For example::
 
@@ -332,13 +336,13 @@ Ansible merges different variables set in inventory so that more specific settin
 
 .. rubric:: Footnotes
 
-.. [1] Tasks in each role will see their own role's defaults. Tasks defined outside of a role will see the last role's defaults.
+.. [1] Tasks in each role see their own role's defaults. Tasks defined outside of a role see the last role's defaults.
 .. [2] Variables defined in inventory file or provided by dynamic inventory.
 .. [3] Includes vars added by 'vars plugins' as well as host_vars and group_vars which are added by the default vars plugin shipped with Ansible.
-.. [4] When created with set_facts's cacheable option, variables will have the high precedence in the play,
-       but will be the same as a host facts precedence when they come from the cache.
+.. [4] When created with set_facts's cacheable option, variables have the high precedence in the play,
+       but are the same as a host facts precedence when they come from the cache.
 
-.. note:: Within any section, redefining a var will override the previous instance.
+.. note:: Within any section, redefining a var overrides the previous instance.
           If multiple groups have the same variable, the last one loaded wins.
           If you define a variable twice in a play's ``vars:`` section, the second one wins.
 .. note:: The previous describes the default config ``hash_behaviour=replace``, switch to ``merge`` to only partially overwrite.
@@ -363,7 +367,7 @@ Tips on where to set variables
 
 You should choose where to define a variable based on the kind of control you might want over values.
 
-Set variables in inventory that deal with geography or behavior. Since groups are frequently the entity that maps roles onto hosts, you can often set variables on the group instead of defining them on a role. Remember:  Child groups override parent groups, and host variables override group variables. See :ref:`define_variables_in_inventory` for details on setting host and group variables.
+Set variables in inventory that deal with geography or behavior. Since groups are frequently the entity that maps roles onto hosts, you can often set variables on the group instead of defining them on a role. Remember: child groups override parent groups, and host variables override group variables. See :ref:`define_variables_in_inventory` for details on setting host and group variables.
 
 Set common defaults in a ``group_vars/all`` file. See :ref:`splitting_out_vars` for details on how to organize host and group variables in your inventory. Group variables are generally placed alongside your inventory file, but they can also be returned by dynamic inventory (see :ref:`intro_dynamic_inventory`) or defined in :ref:`ansible_tower` from the UI or API::