Backportapalooza 09 29 (#78928)

* iss#72389: Adds note and polishes docs/docsite/rst/tips_tricks/sample_setup.rst (#78858)

Co-authored-by: Jaroslav Klech <jklech@redhat.com>
(cherry picked from commit 964e2bc6fe640adbece7efbf55cbffe99e4bf08e)

* Fixes typo in rst format (#78884)

.. hint:: requires a blank line above and below.

(cherry picked from commit 71adb02142dbbd8f3c083ab2921f0d4b651edf64)

* Update yum.py (#78829)

##### SUMMARY
The entire yum command should be highlighted, not only its options.

##### ISSUE TYPE
- Docs Pull Request

+label: docsite_pr

(cherry picked from commit f8f76c5886461d7a44bd3290337a44bccf1666b0)

* Add Ansible community 7.x porting guide (#78916)

(cherry picked from commit 0884a7cf0e404e17767d822080a1f7f672f69520)

* Fixed spelling (#78911)

(cherry picked from commit ae66d9a1f42ef6db3983fdfb996380650a54581b)

* Add message about viewing chat history when on IRC (#78834)

(cherry picked from commit 0343ae46d24e0179c1487ca096391667ca75bec4)

Co-authored-by: JaroslavKlech <klechh@gmail.com>
Co-authored-by: Anwesha Das <anwesha@das.community>
Co-authored-by: Olivier Clavel <olivier.clavel@gmail.com>
Co-authored-by: Christian Adams <chadams@redhat.com>
Co-authored-by: Joel McGuire <jlmcguire4@gmail.com>
Co-authored-by: Greg "Gwmngilfen" Sutcliffe <github@emeraldreverie.org>

1 files changed, 20 insertions, 22 deletions

diff --git a/docs/docsite/rst/tips_tricks/sample_setup.rst b/docs/docsite/rst/tips_tricks/sample_setup.rst
index 1f267a72c7..068677ac1d 100644
--- a/docs/docsite/rst/tips_tricks/sample_setup.rst
+++ b/docs/docsite/rst/tips_tricks/sample_setup.rst
@@ -4,9 +4,9 @@
 Sample Ansible setup
 ********************
 
-You have learned about playbooks, inventory, roles, and variables. This section pulls all those elements together, outlining a sample setup for automating a web service. You can find more example playbooks illustrating these patterns in our `ansible-examples repository <https://github.com/ansible/ansible-examples>`_.  (NOTE: These may not use all of the features in the latest release, but are still an excellent reference!).
+You have learned about playbooks, inventory, roles, and variables. This section combines all those elements, and outlines a sample setup for automating a web service. You can find more example playbooks that illustrate these patterns in our `ansible-examples repository <https://github.com/ansible/ansible-examples>`_. (NOTE: These examples do not use all of the latest features, but are still an excellent reference.).
 
-The sample setup organizes playbooks, roles, inventory, and variables files by function, with tags at the play and task level for greater granularity and control. This is a powerful and flexible approach, but there are other ways to organize Ansible content. Your usage of Ansible should fit your needs, not ours, so feel free to modify this approach and organize your content as you see fit.
+The sample setup organizes playbooks, roles, inventory, and files with variables by function. Tags at the play and task level provide greater granularity and control. This is a powerful and flexible approach, but there are other ways to organize Ansible content. Your usage of Ansible should fit your needs, so feel free to modify this approach and organize your content accordingly.
 
 .. contents::
    :local:
@@ -39,12 +39,12 @@ This layout organizes most tasks in roles, with a single inventory file for each
         webservers-extra.yml  # <-- avoids confusing playbook with task files
 .. include:: shared_snippets/role_directory.txt
 
-.. note:: By default, Ansible assumes your playbooks are stored in one directory with roles stored in a sub-directory called ``roles/``. As you use Ansible to automate more tasks, you may want to move your playbooks into a sub-directory called ``playbooks/``. If you do this, you must configure the path to your ``roles/`` directory using the ``roles_path`` setting in ansible.cfg.
+.. note:: By default, Ansible assumes your playbooks are stored in one directory with roles stored in a sub-directory called ``roles/``. With more tasks to automate, you can consider moving your playbooks into a sub-directory called ``playbooks/``. If you do this, you must configure the path to your ``roles/`` directory using the ``roles_path`` setting in the ``ansible.cfg`` file.
 
 Alternative directory layout
 ----------------------------
 
-Alternatively you can put each inventory file with its ``group_vars``/``host_vars`` in a separate directory. This is particularly useful if your ``group_vars``/``host_vars`` don't have that much in common in different environments. The layout could look something like this:
+You can also put each inventory file with its ``group_vars``/``host_vars`` in a separate directory. This is particularly useful if your ``group_vars``/``host_vars`` do not have that much in common in different environments. The layout could look like this example:
 
   .. code-block:: console
 
@@ -88,7 +88,7 @@ This layout gives you more flexibility for larger environments, as well as a tot
 Sample group and host variables
 -------------------------------
 
-These sample group and host variables files record the variable values that apply to each machine or group of machines. For instance, the data center in Atlanta has its own NTP servers, so when setting up ntp.conf, we should use them:
+These sample group and host files with variables contain the values that apply to each machine or a group of machines. For instance, the data center in Atlanta has its own NTP servers. As a result, when setting up the ``ntp.conf`` file, you could use similar code as in this example:
 
   .. code-block:: yaml
 
@@ -97,7 +97,7 @@ These sample group and host variables files record the variable values that appl
     ntp: ntp-atlanta.example.com
     backup: backup-atlanta.example.com
 
-Similarly, the webservers have some configuration that does not apply to the database servers:
+Similarly, hosts in the webservers group have some configuration that does not apply to the database servers:
 
   .. code-block:: yaml
 
@@ -106,7 +106,7 @@ Similarly, the webservers have some configuration that does not apply to the dat
     apacheMaxRequestsPerChild: 3000
     apacheMaxClients: 900
 
-Default values, or values that are universally true, belong in a file called group_vars/all:
+Default values, or values that are universally true, belong in a file called ``group_vars/all``:
 
   .. code-block:: yaml
 
@@ -115,7 +115,7 @@ Default values, or values that are universally true, belong in a file called gro
     ntp: ntp-boston.example.com
     backup: backup-boston.example.com
 
-If necessary, you can define specific hardware variance in systems in a host_vars file:
+If necessary, you can define specific hardware variance in systems in the ``host_vars`` directory:
 
   .. code-block:: yaml
 
@@ -124,14 +124,17 @@ If necessary, you can define specific hardware variance in systems in a host_var
     foo_agent_port: 86
     bar_agent_port: 99
 
-Again, if you are using :ref:`dynamic inventory <dynamic_inventory>`, Ansible creates many dynamic groups automatically.  So a tag like "class:webserver" would load in variables from the file "group_vars/ec2_tag_class_webserver" automatically.
+If you use :ref:`dynamic inventory <dynamic_inventory>`, Ansible creates many dynamic groups automatically. As a result, a tag like ``class:webserver`` will load in variables from the file ``group_vars/ec2_tag_class_webserver`` automatically.
+
+.. note:: You can access host variables with a special variable called ``hostvars``. See :ref:`special_variables` for a list of these variables. The ``hostvars`` variable can access only host-specific variables, not group variables.
+
 
 .. _split_by_role:
 
 Sample playbooks organized by function
 --------------------------------------
 
-With this setup, a single playbook can define all the infrastructure. The site.yml playbook imports two other playbooks, one for the webservers and one for the database servers:
+With this setup, a single playbook can define the entire infrastructure. The ``site.yml`` playbook imports two other playbooks. One for the webservers and one for the database servers:
 
   .. code-block:: yaml
 
@@ -140,7 +143,7 @@ With this setup, a single playbook can define all the infrastructure. The site.y
     - import_playbook: webservers.yml
     - import_playbook: dbservers.yml
 
-The webservers.yml file, also at the top level, maps the configuration of the webservers group to the roles related to the webservers group:
+The ``webservers.yml`` playbook, also at the top level, maps the configuration of the webservers group to the roles related to the webservers group:
 
   .. code-block:: yaml
 
@@ -151,7 +154,7 @@ The webservers.yml file, also at the top level, maps the configuration of the we
         - common
         - webtier
 
-With this setup, you can configure your whole infrastructure by "running" site.yml, or run a subset by running webservers.yml.  This is analogous to the Ansible "--limit" parameter but a little more explicit:
+With this setup, you can configure your entire infrastructure by running ``site.yml``. Alternatively, to configure just a portion of your infrastructure, run ``webservers.yml``. This is similar to the Ansible ``--limit`` parameter but a little more explicit:
 
   .. code-block:: shell
 
@@ -163,7 +166,7 @@ With this setup, you can configure your whole infrastructure by "running" site.y
 Sample task and handler files in a function-based role
 ------------------------------------------------------
 
-Ansible loads any file called ``main.yml`` in a role sub-directory. This sample ``tasks/main.yml`` file is simple - it sets up NTP, but it could do more if we wanted:
+Ansible loads any file called ``main.yml`` in a role sub-directory. This sample ``tasks/main.yml`` file configures NTP:
 
   .. code-block:: yaml
 
@@ -191,8 +194,7 @@ Ansible loads any file called ``main.yml`` in a role sub-directory. This sample
         enabled: yes
       tags: ntp
 
-Here is an example handlers file.  As a review, handlers are only fired when certain tasks report changes, and are run at the end
-of each play:
+Here is an example handlers file. Handlers are only triggered when certain tasks report changes. Handlers run at the end of each play:
 
   .. code-block:: yaml
 
@@ -264,20 +266,16 @@ To discover what tasks would run or what hostnames would be affected by a partic
 Organizing for deployment or configuration
 ------------------------------------------
 
-The sample setup models a typical configuration topology.  When doing multi-tier deployments, there are going
-to be some additional playbooks that hop between tiers to roll out an application. In this case, 'site.yml'
-may be augmented by playbooks like 'deploy_exampledotcom.yml' but the general concepts still apply. Ansible allows you to deploy and configure using the same tool, so you would likely reuse groups and keep the OS configuration in separate playbooks or roles from the app deployment.
+The sample setup illustrates a typical configuration topology. When you do multi-tier deployments, you will likely need some additional playbooks that hop between tiers to roll out an application. In this case, you can augment ``site.yml`` with playbooks like ``deploy_exampledotcom.yml``. However, the general concepts still apply. With Ansible you can deploy and configure using the same utility. Therefore, you will probably reuse groups and keep the OS configuration in separate playbooks or roles from the application deployment.
 
-Consider "playbooks" as a sports metaphor -- you can have one set of plays to use against all your infrastructure and situational plays that you use at different times and for different purposes.
+Consider "playbooks" as a sports metaphor -- you can have one set of plays to use against all your infrastructure. Then you have situational plays that you use at different times and for different purposes.
 
 .. _ship_modules_with_playbooks:
 
 Using local Ansible modules
 ---------------------------
 
-If a playbook has a :file:`./library` directory relative to its YAML file, this directory can be used to add Ansible modules that will
-automatically be in the Ansible module path.  This is a great way to keep modules that go with a playbook together.  This is shown
-in the directory structure example at the start of this section.
+If a playbook has a :file:`./library` directory relative to its YAML file, you can use this directory to add Ansible modules automatically to the module path. This organizes modules with playbooks. For example, see the directory structure at the start of this section.
 
 .. seealso::