restructure headings and copy-edit shell completion (#66479) (#66536)

* Docs: restructure headings and fix shell completion on installation guide, apply suggestions from code review

(cherry picked from commit 599cc0bdfa762819962108c5933b74429623e8d2)

1 files changed, 115 insertions, 118 deletions

diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst
index 0b2078f174..2f75842933 100644
--- a/docs/docsite/rst/installation_guide/intro_installation.rst
+++ b/docs/docsite/rst/installation_guide/intro_installation.rst
@@ -1,49 +1,30 @@
 .. _installation_guide:
 .. _intro_installation_guide:
 
-Installation Guide
-==================
+Installing Ansible
+===================
 
-.. contents:: Topics
+This page describes how to install Ansible on different platforms.
+Ansible is an agentless automation tool that by default manages machines over the SSH protocol. Once installed, Ansible does
+not add a database, and there will be no daemons to start or keep running.  You only need to install it on one machine (which could easily be a laptop) and it can manage an entire fleet of remote machines from that central point.  When Ansible manages remote machines, it does not leave software installed or running on them, so there's no real question about how to upgrade Ansible when moving to a new version.
 
-Welcome to the Ansible Installation Guide!
 
-.. _what_will_be_installed:
+.. contents::
+  :local:
 
-Basics / What Will Be Installed
-```````````````````````````````
+Prerequisites
+--------------
 
-Ansible by default manages machines over the SSH protocol.
-
-Once Ansible is installed, it will not add a database, and there will be no daemons to start or keep running.  You only need to install it on one machine (which could easily be a laptop) and it can manage an entire fleet of remote machines from that central point.  When Ansible manages remote machines, it does not leave software installed or running on them, so there's no real question about how to upgrade Ansible when moving to a new version.
-
-.. _what_version:
-
-What Version To Pick?
-`````````````````````
-
-Because it runs so easily from source and does not require any installation of software on remote
-machines, many users will actually track the development version.
-
-Ansible's release cycles are usually about four months long. Due to this short release cycle,
-minor bugs will generally be fixed in the next release versus maintaining backports on the stable branch.
-Major bugs will still have maintenance releases when needed, though these are infrequent.
-
-If you are wishing to run the latest released version of Ansible and you are running Red Hat Enterprise Linux (TM), CentOS, Fedora, Debian, or Ubuntu, we recommend using the OS package manager.
-
-For other installation options, we recommend installing via ``pip``, which is the Python package manager.
-
-If you wish to track the development release to use and test the latest features, we will share
-information about running from source. It's not necessary to install the program to run from source.
+You install Ansible on a control node, which then uses SSH (by default) to communicate with your managed nodes (those end devices you want to automate).
 
 .. _control_node_requirements:
 
-Control Node Requirements
-````````````````````````````
-
-Currently Ansible can be run from any machine with Python 2 (version 2.7) or Python 3 (versions 3.5 and higher) installed. Windows is not supported for the control node.
+Control node requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
+Currently Ansible can be run from any machine with Python 2 (version 2.7) or Python 3 (versions 3.5 and higher) installed.
 This includes Red Hat, Debian, CentOS, macOS, any of the BSDs, and so on.
+Windows is not supported for the control node.
 
 When choosing a control node, bear in mind that any management system benefits from being run near the machines being managed. If you are running Ansible in a cloud, consider running it from a machine inside that cloud. In most cases this will work better than on the open Internet.
 
@@ -54,16 +35,16 @@ When choosing a control node, bear in mind that any management system benefits f
 
 .. warning::
 
-    Please note that some modules and plugins have additional requirements. For modules these need to be satisfied on the 'target' machine and should be listed in the module specific docs.
+    Please note that some modules and plugins have additional requirements. For modules these need to be satisfied on the 'target' machine (the managed node) and should be listed in the module specific docs.
 
 .. _managed_node_requirements:
 
-Managed Node Requirements
-`````````````````````````
+Managed node requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-On the managed nodes, you need a way to communicate, which is normally ssh. By
-default this uses sftp. If that's not available, you can switch to scp in
-:file:`ansible.cfg`.  You also need Python 2 (version 2.6 or later) or Python 3 (version 3.5 or
+On the managed nodes, you need a way to communicate, which is normally SSH. By
+default this uses SFTP. If that's not available, you can switch to SCP in
+:ref:`ansible.cfg <ansible_configuration_settings>`.  You also need Python 2 (version 2.6 or later) or Python 3 (version 3.5 or
 later).
 
 .. note::
@@ -73,7 +54,7 @@ later).
      can use the :ref:`yum module<yum_module>` or :ref:`dnf module<dnf_module>` in Ansible to install this package on remote systems
      that do not have it.
 
-   * By default, Ansible uses the python interpreter located at :file:`/usr/bin/python` to run its
+   * By default, Ansible uses the Python interpreter located at :file:`/usr/bin/python` to run its
      modules.  However, some Linux distributions may only have a Python 3 interpreter installed to
      :file:`/usr/bin/python3` by default.  On those systems, you may see an error like::
 
@@ -88,20 +69,37 @@ later).
      on a client side install of Python to run.  Technically, you can use Ansible to install a compatible
      version of Python using the :ref:`raw module<raw_module>`, which then allows you to use everything else.
      For example, if you need to bootstrap Python 2 onto a RHEL-based system, you can install it
-     via
+     as follows:
 
      .. code-block:: shell
 
         $ ansible myhost --become -m raw -a "yum install -y python2"
 
-.. _installing_the_control_node:
+.. _what_version:
+
+Selecting an Ansible version to install
+---------------------------------------
+
+Which Ansible version to install is based on your particular needs. You can choose any of the following ways to install Ansible:
+
+* Install the latest release with your OS package manager (for Red Hat Enterprise Linux (TM), CentOS, Fedora, Debian, or Ubuntu).
+* Install with ``pip`` (the Python package manager).
+* Install from source to access the development (``devel``) version to use and test the latest features.
 
-Installing the Control Node
-``````````````````````````````
+
+Because Ansible runs so easily from source and does not require any installation of software on remote
+machines, many users will actually track the development version.
+
+Ansible creates new releases two to three times a year. Due to this short release cycle,
+minor bugs will generally be fixed in the next release versus maintaining backports on the stable branch.
+Major bugs will still have maintenance releases when needed, though these are infrequent.
+
+
+.. _installing_the_control_node:
 .. _from_yum:
 
-Latest Release via DNF or Yum
-+++++++++++++++++++++++++++++
+Installing Ansible on RHEL, CentOS, or Fedora
+----------------------------------------------
 
 On Fedora:
 
@@ -144,12 +142,12 @@ You can also build an RPM yourself. From the root of a checkout or tarball, use
 
 .. _from_apt:
 
-Latest Releases via Apt (Ubuntu)
-++++++++++++++++++++++++++++++++
+Installing Ansible on Ubuntu
+----------------------------
 
 Ubuntu builds are available `in a PPA here <https://launchpad.net/~ansible/+archive/ubuntu/ansible>`_.
 
-To configure the PPA on your machine and install ansible run these commands:
+To configure the PPA on your machine and install Ansible run these commands:
 
 .. code-block:: bash
 
@@ -166,10 +164,10 @@ Debian/Ubuntu packages can also be built from the source checkout, run:
 
     $ make deb
 
-You may also wish to run from source to get the latest, which is covered below.
+You may also wish to run from source to get the development branch, which is covered below.
 
-Latest Releases via Apt (Debian)
-++++++++++++++++++++++++++++++++
+Installing Ansible on Debian
+----------------------------
 
 Debian users may leverage the same source as the Ubuntu PPA.
 
@@ -189,21 +187,21 @@ Then run these commands:
 
 .. note:: This method has been verified with the Trusty sources in Debian Jessie and Stretch but may not be supported in earlier versions. You may want to use ``apt-get`` instead of ``apt`` in older versions.
 
-Latest Releases via Portage (Gentoo)
-++++++++++++++++++++++++++++++++++++
+Installing Ansible on Gentoo with portage
+-----------------------------------------
 
 .. code-block:: bash
 
     $ emerge -av app-admin/ansible
 
-To install the newest version, you may need to unmask the ansible package prior to emerging:
+To install the newest version, you may need to unmask the Ansible package prior to emerging:
 
 .. code-block:: bash
 
     $ echo 'app-admin/ansible' >> /etc/portage/package.accept_keywords
 
-Latest Releases via pkg (FreeBSD)
-+++++++++++++++++++++++++++++++++
+Installing Ansible on FreeBSD
+-----------------------------
 
 Though Ansible works with both Python 2 and 3 versions, FreeBSD has different packages for each Python version.
 So to install you can use:
@@ -235,17 +233,17 @@ Older versions of FreeBSD worked with something like this (substitute for your c
 
 .. _on_macos:
 
-Latest Releases on macOS
-++++++++++++++++++++++++++
+Installing Ansible on macOS
+---------------------------
 
-The preferred way to install Ansible on a Mac is via ``pip``.
+The preferred way to install Ansible on a Mac is with ``pip``.
 
-The instructions can be found in `Latest Releases via Pip`_ section. If you are running macOS version 10.12 or older, then you should upgrade to the latest ``pip`` to connect to the Python Package Index securely.
+The instructions can be found in :ref:`from_pip`. If you are running macOS version 10.12 or older, then you should upgrade to the latest ``pip`` to connect to the Python Package Index securely.
 
 .. _from_pkgutil:
 
-Latest Releases via OpenCSW (Solaris)
-+++++++++++++++++++++++++++++++++++++
+Installing Ansible on Solaris
+-----------------------------
 
 Ansible is available for Solaris as `SysV package from OpenCSW <https://www.opencsw.org/packages/ansible/>`_.
 
@@ -256,8 +254,8 @@ Ansible is available for Solaris as `SysV package from OpenCSW <https://www.open
 
 .. _from_pacman:
 
-Latest Releases via Pacman (Arch Linux)
-+++++++++++++++++++++++++++++++++++++++
+Installing Ansible on Arch Linux
+---------------------------------
 
 Ansible is available in the Community repository::
 
@@ -269,8 +267,8 @@ Also see the `Ansible <https://wiki.archlinux.org/index.php/Ansible>`_ page on t
 
 .. _from_sbopkg:
 
-Latest Releases via sbopkg (Slackware Linux)
-++++++++++++++++++++++++++++++++++++++++++++
+Installing Ansible on Slackware Linux
+-------------------------------------
 
 Ansible build script is available in the `SlackBuilds.org <https://slackbuilds.org/apps/ansible/>`_ repository.
 Can be built and installed using `sbopkg <https://sbopkg.org/>`_.
@@ -279,14 +277,14 @@ Create queue with Ansible and all dependencies::
 
     # sqg -p ansible
 
-Build and install packages from created queuefile (answer Q for question if sbopkg should use queue or package)::
+Build and install packages from a created queuefile (answer Q for question if sbopkg should use queue or package)::
 
     # sbopkg -k -i ansible
 
 .. _from swupd:
 
-Latest Release via swupd (Clear Linux)
-+++++++++++++++++++++++++++++++++++++++
+Installing Ansible on Clear Linux
+---------------------------------
 
 Ansible and its dependencies are available as part of the sysadmin host management bundle::
 
@@ -298,10 +296,10 @@ Update of the software will be managed by the swupd tool::
 
 .. _from_pip:
 
-Latest Releases via Pip
-+++++++++++++++++++++++
+Installing Ansible with ``pip``
+--------------------------------
 
-Ansible can be installed via ``pip``, the Python package manager.  If ``pip`` isn't already available on your system of Python, run the following commands to install it::
+Ansible can be installed with ``pip``, the Python package manager.  If ``pip`` isn't already available on your system of Python, run the following commands to install it::
 
     $ curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
     $ python get-pip.py --user
@@ -310,7 +308,7 @@ Then install Ansible [1]_::
 
     $ pip install --user ansible
 
-Or if you are looking for the latest development version::
+Or if you are looking for the development version::
 
     $ pip install --user git+https://github.com/ansible/ansible.git@devel
 
@@ -343,22 +341,12 @@ If you wish to install Ansible globally, run the following commands::
     Please make sure you have the latest version of ``pip`` before installing Ansible.
     If you have an older version of ``pip`` installed, you can upgrade by following `pip's upgrade instructions <https://pip.pypa.io/en/stable/installing/#upgrading-pip>`_ .
 
-.. _tagged_releases:
-
-Tarballs of Tagged Releases
-+++++++++++++++++++++++++++
-
-Packaging Ansible or wanting to build a local package yourself, but don't want to do a git checkout?  Tarballs of releases are available on the `Ansible downloads <https://releases.ansible.com/ansible>`_ page.
-
-These releases are also tagged in the `git repository <https://github.com/ansible/ansible/releases>`_ with the release version.
-
-
 
 
 .. _from_source:
 
-Running From Source
-+++++++++++++++++++
+Running Ansible from source (devel)
+-----------------------------------
 
 Ansible is easy to run from source. You do not need ``root`` permissions
 to use it and there is no software to actually install. No daemons
@@ -370,7 +358,7 @@ open source projects.
 
 .. note::
 
-   If you are want to use Ansible Tower as the Control Node, do not use a source installation of Ansible. Please use an OS package manager (like ``apt`` or ``yum``) or ``pip`` to install a stable version.
+   If you want to use Ansible Tower as the control node, do not use a source installation of Ansible. Please use an OS package manager (like ``apt`` or ``yum``) or ``pip`` to install a stable version.
 
 
 To install from source, clone the Ansible git repository:
@@ -407,7 +395,7 @@ Ansible also uses the following Python modules that need to be installed [1]_:
 
     $ pip install --user -r ./requirements.txt
 
-To update ansible checkouts, use pull-with-rebase so any local changes are replayed.
+To update Ansible checkouts, use pull-with-rebase so any local changes are replayed.
 
 .. code-block:: bash
 
@@ -427,7 +415,7 @@ other than ``/etc/ansible/hosts``:
     $ echo "127.0.0.1" > ~/ansible_hosts
     $ export ANSIBLE_INVENTORY=~/ansible_hosts
 
-You can read more about the inventory file in later parts of the manual.
+You can read more about the inventory file at :ref:`inventory`.
 
 Now let's test things with a ping command:
 
@@ -437,23 +425,30 @@ Now let's test things with a ping command:
 
 You can also use "sudo make install".
 
-.. _shell_completion:
+.. _tagged_releases:
+
+Finding tarballs of tagged releases
+-----------------------------------
 
-Shell Completion
-````````````````
+Packaging Ansible or wanting to build a local package yourself, but don't want to do a git checkout?  Tarballs of releases are available on the `Ansible downloads <https://releases.ansible.com/ansible>`_ page.
 
-As of Ansible 2.9 shell completion of the ansible command line utilities is available and provided through an optional dependency
-called ``argcomplete``. ``argcomplete`` supports bash, and limited support for zsh and tcsh
+These releases are also tagged in the `git repository <https://github.com/ansible/ansible/releases>`_ with the release version.
 
-``python-argcomplete`` can be installed from EPEL on Red Hat Enterprise based distributions, and is available in the standard OS repositories for many other distributions.
 
-For more information about installing and configuration see the `argcomplete documentation <https://argcomplete.readthedocs.io/en/latest/>_`.
+.. _shell_completion:
 
-Installing
-++++++++++
+Ansible command shell completion
+--------------------------------
 
-via yum/dnf
------------
+As of Ansible 2.9, shell completion of the Ansible command line utilities is available and provided through an optional dependency
+called ``argcomplete``. ``argcomplete`` supports bash, and has limited support for zsh and tcsh.
+
+You can install ``python-argcomplete`` from EPEL on Red Hat Enterprise based distributions, and or from the standard OS repositories for many other distributions.
+
+For more information about installing and configuration see the `argcomplete documentation <https://argcomplete.readthedocs.io/en/latest/>`_.
+
+Installing ``argcomplete`` on RHEL, CentOS, or Fedora
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 On Fedora:
 
@@ -468,40 +463,42 @@ On RHEL and CentOS:
     $ sudo yum install epel-release
     $ sudo yum install python-argcomplete
 
-via apt
--------
+
+Installing ``argcomplete`` with ``apt``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: bash
 
     $ sudo apt install python-argcomplete
 
-via pip
--------
+
+Installing ``argcomplete`` with ``pip``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: bash
 
     $ pip install argcomplete
 
-Configuring
-+++++++++++
+Configuring ``argcomplete``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-There are 2 ways to configure argcomplete to allow shell completion of the Ansible command line utilities. Per command, or globally.
+There are 2 ways to configure ``argcomplete`` to allow shell completion of the Ansible command line utilities: globally or per command.
 
 Globally
---------
+"""""""""
 
-Global completion requires bash 4.2
+Global completion requires bash 4.2.
 
 .. code-block:: bash
 
     $ sudo activate-global-python-argcomplete
 
-This will write a bash completion file to a global location, use ``--dest`` to change the location
+This will write a bash completion file to a global location. Use ``--dest`` to change the location.
 
-Per Command
------------
+Per command
+"""""""""""
 
-If you do not have bash 4.2, you must register each script independently
+If you do not have bash 4.2, you must register each script independently.
 
 .. code-block:: bash
 
@@ -515,17 +512,17 @@ If you do not have bash 4.2, you must register each script independently
     $ eval $(register-python-argcomplete ansible-pull)
     $ eval $(register-python-argcomplete ansible-vault)
 
-It would be advisable to place the above commands, into your shells profile file such as ``~/.profile`` or ``~/.bash_profile``.
+You should place the above commands into your shells profile file such as ``~/.profile`` or ``~/.bash_profile``.
 
-Zsh or tcsh
------------
+``argcomplete`` with zsh or tcsh
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-See the `argcomplete documentation <https://argcomplete.readthedocs.io/en/latest/>_`.
+See the `argcomplete documentation <https://argcomplete.readthedocs.io/en/latest/>`_.
 
 .. _getting_ansible:
 
 Ansible on GitHub
-`````````````````
+-----------------
 
 You may also wish to follow the `GitHub project <https://github.com/ansible/ansible>`_ if
 you have a GitHub account. This is also where we keep the issue tracker for sharing