revises inventory intro page (#49330)

* revises inventory intro page

* changes :doc: to :ref: for links

docs/docsite/rst/user_guide/intro_inventory.rst

@@ -1,11 +1,12 @@
 .. _intro_inventory:
 .. _inventory:
 
-
+**********************
 Working with Inventory
-======================
+**********************
 
-.. contents:: Topics
+.. contents::
+   :local:
 
 Ansible works against multiple systems in your infrastructure at the same time.
 It does this by selecting portions of systems listed in Ansible's inventory,
@@ -18,8 +19,8 @@ Introduced in version 2.4, Ansible has inventory plugins to make this flexible a
 
 .. _inventoryformat:
 
-Hosts and Groups
-++++++++++++++++
+Inventory basics: hosts and groups
+==================================
 
 The inventory file can be in one of many formats, depending on the inventory plugins you have.
 For this example, the format for ``/etc/ansible/hosts`` is an INI-like (one of Ansible's defaults) and looks like this:
@@ -129,8 +130,8 @@ As mentioned above, setting these in the inventory file is only a shorthand, and
 
 .. _host_variables:
 
-Host Variables
-++++++++++++++
+Assigning a variable to one machine: host variables
+===================================================
 
 As described above, it is easy to assign variables to hosts that will be used later in playbooks:
 
@@ -154,8 +155,8 @@ The YAML version:
 
 .. _group_variables:
 
-Group Variables
-+++++++++++++++
+Assigning a variable to many machines: group variables
+======================================================
 
 Variables can also be applied to an entire group at once:
 
@@ -187,11 +188,11 @@ Be aware that this is only a convenient way to apply variables to multiple hosts
 
 .. _subgroups:
 
-Groups of Groups, and Group Variables
-+++++++++++++++++++++++++++++++++++++
+Inheriting variable values: group variables for groups of groups
+----------------------------------------------------------------
 
-It is also possible to make groups of groups using the ``:children`` suffix in INI or the ``children:`` entry in YAML.
-You can apply variables using ``:vars`` or ``vars:``:
+You can make groups of groups using the ``:children`` suffix in INI or the ``children:`` entry in YAML.
+You can apply variables to these groups of groups using ``:vars`` or ``vars:``:
 
 
 .. code-block:: guess
@@ -256,7 +257,7 @@ Child groups have a couple of properties to note:
 .. _default_groups:
 
 Default groups
-++++++++++++++
+==============
 
 There are two default groups: ``all`` and ``ungrouped``. ``all`` contains every host.
 ``ungrouped`` contains all hosts that don't have another group aside from ``all``.
@@ -265,22 +266,18 @@ Though ``all`` and ``ungrouped`` are always present, they can be implicit and no
 
 .. _splitting_out_vars:
 
-Splitting Out Host and Group Specific Data
-++++++++++++++++++++++++++++++++++++++++++
+Organizing host and group variables
+===================================
 
-The preferred practice in Ansible is to not store variables in the main inventory file.
+Although you can store variables in the main inventory file, storing separate host and group variables files may help you track your variable values more easily.
 
-In addition to storing variables directly in the inventory file, host and group variables can be stored in individual files relative to the inventory file (not directory, it is always the file).
+Host and group variables can be stored in individual files relative to the inventory file (not directory, it is always the file).
 
 These variable files are in YAML format. Valid file extensions include '.yml', '.yaml', '.json', or no file extension.
 See :ref:`yaml_syntax` if you are new to YAML.
 
-Assuming the inventory file path is::
-
-    /etc/ansible/hosts
-
-If the host is named 'foosball', and in groups 'raleigh' and 'webservers', variables
-in YAML files at the following locations will be made available to the host::
+Let's say, for example, that you keep your inventory file at ``/etc/ansible/hosts``. You have a host named 'foosball' that's a member of two groups: 'raleigh' and 'webservers'. That host will use variables
+in YAML files at the following locations::
 
     /etc/ansible/group_vars/raleigh # can optionally end in '.yml', '.yaml', or '.json'
     /etc/ansible/group_vars/webservers
@@ -304,7 +301,7 @@ Ansible will read all the files in these directories in lexicographical order. A
 
 All hosts that are in the 'raleigh' group will have the variables defined in these files
 available to them. This can be very useful to keep your variables organized when a single
-file starts to be too big, or when you want to use :doc:`Ansible Vault<playbooks_vault>` on a part of a group's
+file starts to be too big, or when you want to use :ref:`Ansible Vault<playbooks_vault>` on a part of a group's
 variables.
 
 Tip: The ``group_vars/`` and ``host_vars/`` directories can exist in
@@ -320,8 +317,8 @@ is an excellent way to track changes to your inventory and host variables.
 
 .. _how_we_merge:
 
-How Variables Are Merged
-++++++++++++++++++++++++
+How variables are merged
+========================
 
 By default variables are merged/flattened to the specific host before a play is run. This keeps Ansible focused on the Host and Task, so groups don't really survive outside of inventory and host matching. By default, Ansible overwrites variables including the ones defined for a group and/or host (see :ref:`DEFAULT_HASH_BEHAVIOUR<DEFAULT_HASH_BEHAVIOUR>`). The order/precedence is (from lowest to highest):
 
@@ -348,8 +345,8 @@ In this example, if both groups have the same priority, the result would normall
 
 .. _behavioral_parameters:
 
-List of Behavioral Inventory Parameters
-+++++++++++++++++++++++++++++++++++++++
+Connecting to hosts: behavioral inventory parameters
+====================================================
 
 As described above, setting the following variables control how Ansible interacts with remote hosts.
 
@@ -392,7 +389,7 @@ ansible_ssh_executable (added in version 2.2)
     This setting overrides the default behavior to use the system :command:`ssh`. This can override the ``ssh_executable`` setting in :file:`ansible.cfg`.
 
 
-Privilege escalation (see :doc:`Ansible Privilege Escalation<become>` for further details):
+Privilege escalation (see :ref:`Ansible Privilege Escalation<become>` for further details):
 
 ansible_become
     Equivalent to ``ansible_sudo`` or ``ansible_su``, allows to force privilege escalation
@@ -449,7 +446,7 @@ Examples from an Ansible-INI host file::
   ruby_module_host  ansible_ruby_interpreter=/usr/bin/ruby.1.9.3
 
 Non-SSH connection types
-++++++++++++++++++++++++
+------------------------
 
 As stated in the previous section, Ansible executes playbooks over SSH but it is not limited to this connection type.
 With the host specific parameter ``ansible_connection=<connector>``, the connection type can be changed.