Update Documentation

Applying RST formatting conventions [1],[2] and [3]
[1] http://docs.openstack.org/contributor-guide/rst-conv/gen-guidelines.html
[2] http://docs.openstack.org/contributor-guide/rst-conv/inline-markups.html
[3] http://docs.openstack.org/contributor-guide/rst-conv/lists.html
Change-Id: I38b77a45d30ca0542058675dd1e8aba790c68567
Partially-implements: blueprint documentation-rework

1 files changed, 88 insertions, 90 deletions

diff --git a/doc/quickstart.rst b/doc/quickstart.rst
index cbaf15289..8f4663ae5 100644
--- a/doc/quickstart.rst
+++ b/doc/quickstart.rst
@@ -19,21 +19,21 @@ Recommended Environment
 =======================
 
 If developing or evaluating Kolla, the community strongly recommends using bare
-metal or a virtual machine.  Follow the instructions in this document to get
+metal or a virtual machine. Follow the instructions in this document to get
 started with deploying OpenStack on bare metal or a virtual machine with Kolla.
 There are other deployment environments referenced below in `Additional Environments`_.
 
 Install Dependencies
 ====================
 
-Kolla is tested on CentOS, Oracle Linux, RHEL and Ubuntu as both container
-OS platforms and bare metal deployment targets.
+Kolla is tested on CentOS, Oracle Linux, RHEL and Ubuntu as both container OS
+platforms and bare metal deployment targets.
 
 Fedora: Kolla will not run on Fedora 22 and later as a bare metal deployment
 target. These distributions compress kernel modules with the .xz compressed
 format. The guestfs system in the CentOS family of containers cannot read
-these images because a dependent package supermin in CentOS needs to be
-updated to add .xz compressed format support.
+these images because a dependent package supermin in CentOS needs to be updated
+to add .xz compressed format support.
 
 Ubuntu: For Ubuntu based systems where Docker is used it is recommended to use
 the latest available LTS kernel. The latest LTS kernel available is the wily
@@ -45,7 +45,7 @@ and OverlayFS. In order to update kernel in Ubuntu 14.04 LTS to 4.2, run:
 
     apt-get -y install linux-image-generic-lts-wily
 
-.. NOTE:: Install is *very* sensitive about version of components.  Please
+.. NOTE:: Install is *very* sensitive about version of components. Please
   review carefully because default Operating System repos are likely out of
   date.
 
@@ -89,10 +89,10 @@ command:
 
     docker --version
 
-When running with systemd, setup docker-engine with the appropriate
-information in the Docker daemon to launch with. This means setting up the
-following information in the ``docker.service`` file. If you do not set the
-MountFlags option correctly then ``kolla-ansible`` will fail to deploy the
+When running with systemd, setup docker-engine with the appropriate information
+in the Docker daemon to launch with. This means setting up the following
+information in the ``docker.service`` file. If you do not set the MountFlags
+option correctly then ``kolla-ansible`` will fail to deploy the
 ``neutron-dhcp-agent`` container and throws APIError/HTTPError. After adding
 the drop-in unit file as follows, reload and restart the docker service:
 
@@ -135,15 +135,15 @@ Or using ``pip`` to install a latest version:
     pip install -U docker-py
 
 
-OpenStack, RabbitMQ, and Ceph require all hosts to have matching times to ensure
-proper message delivery. In the case of Ceph, it will complain if the hosts
-differ by more than 0.05 seconds. Some OpenStack services have timers as low as
-2 seconds by default. For these reasons it is highly recommended to setup an NTP
-service of some kind. While ``ntpd`` will achieve more accurate time for the
-deployment if the NTP servers are running in the local deployment environment,
-`chrony <http://chrony.tuxfamily.org>`_ is more accurate when syncing the time
-across a WAN connection. When running Ceph it is recommended to setup ``ntpd`` to
-sync time locally due to the tight time constraints.
+OpenStack, RabbitMQ, and Ceph require all hosts to have matching times to
+ensure proper message delivery. In the case of Ceph, it will complain if the
+hosts differ by more than 0.05 seconds. Some OpenStack services have timers as
+low as 2 seconds by default. For these reasons it is highly recommended to
+setup an NTP service of some kind. While ``ntpd`` will achieve more accurate
+time for the deployment if the NTP servers are running in the local deployment
+environment, `chrony <http://chrony.tuxfamily.org>`_ is more accurate when
+syncing the time across a WAN connection. When running Ceph it is recommended
+to setup ``ntpd`` to sync time locally due to the tight time constraints.
 
 To install, start, and enable ntp on CentOS execute the following:
 
@@ -160,9 +160,9 @@ To install and start on Debian based systems execute the following:
 
     apt-get install ntp
 
-Libvirt is started by default on many operating systems. Please disable ``libvirt``
-on any machines that will be deployment targets. Only one copy of libvirt may
-be running at a time.
+Libvirt is started by default on many operating systems. Please disable
+``libvirt`` on any machines that will be deployment targets. Only one copy of
+libvirt may be running at a time.
 
 ::
 
@@ -179,24 +179,24 @@ On Ubuntu, apparmor will sometimes prevent libvirt from working.
 ::
    /usr/sbin/libvirtd: error while loading shared libraries: libvirt-admin.so.0: cannot open shared object file: Permission denied
 
-If you are seeing the libvirt container fail with the error above, disable
-the libvirt profile.
+If you are seeing the libvirt container fail with the error above, disable the
+libvirt profile.
 
 ::
 
    sudo apparmor_parser -R /etc/apparmor.d/usr.sbin.libvirtd
 
 
-Kolla deploys OpenStack using
-`Ansible <http://www.ansible.com>`__. Install Ansible from distribution
-packaging if the distro packaging has recommended version available.
+Kolla deploys OpenStack using `Ansible <http://www.ansible.com>`__. Install
+Ansible from distribution packaging if the distro packaging has recommended
+version available.
 
 Some implemented distro versions of Ansible are too old to use distro
-packaging.  Currently, CentOS and RHEL package Ansible 1.9.4 which is
-suitable for use with Kolla. As Ansible 2.0 is also available, version 1.9
-must be specified. Note that you will need to enable access
-to the EPEL repository to install via yum -- to do so, take a look at
-Fedora's EPEL `docs <https://fedoraproject.org/wiki/EPEL>`__ and
+packaging. Currently, CentOS and RHEL package Ansible 1.9.4 which is suitable
+for use with Kolla. As Ansible 2.0 is also available, version 1.9 must be
+specified. Note that you will need to enable access to the EPEL repository to
+install via yum -- to do so, take a look at Fedora's EPEL
+`docs <https://fedoraproject.org/wiki/EPEL>`__ and
 `FAQ <https://fedoraproject.org/wiki/EPEL/FAQ>`__.
 
 On CentOS or RHEL systems, this can be done using:
@@ -205,16 +205,16 @@ On CentOS or RHEL systems, this can be done using:
 
     yum -y install ansible1.9
 
-Many DEB based systems do not meet Kolla's Ansible version requirements.
-It is recommended to use pip to install Ansible 1.9.4.
-Finally Ansible 1.9.4 may be installed using:
+Many DEB based systems do not meet Kolla's Ansible version requirements. It is
+recommended to use pip to install Ansible 1.9.4. Finally Ansible 1.9.4 may be
+installed using:
 
 ::
 
     pip install -U ansible==1.9.4
 
-If DEB based systems include a version of Ansible that meets Kolla's
-version requirements it can be installed by:
+If DEB based systems include a version of Ansible that meets Kolla's version
+requirements it can be installed by:
 
 ::
 
@@ -274,31 +274,31 @@ To install the clients use:
 Local Registry
 ==============
 
-A local registry is not required for an all-in-one installation.  Check out the
-:doc:`multinode` for more information on using a local registry.  Otherwise, the
-`Docker Hub Image Registry`_ contains all images from each of Kolla's major releases.
-The latest release tag is 2.0.0 for Mitaka.
+A local registry is not required for an ``all-in-one`` installation. Check out
+the :doc:`multinode` for more information on using a local registry. Otherwise,
+the `Docker Hub Image Registry`_ contains all images from each of Kolla's major
+releases. The latest release tag is 2.0.0 for Mitaka.
 
 Additional Environments
 =======================
 
-Two virtualized development environment options are available for Kolla.
-These options permit the development of Kolla without disrupting the host
-operating system.
+Two virtualized development environment options are available for Kolla. These
+options permit the development of Kolla without disrupting the host operating
+system.
 
 If developing Kolla on an OpenStack cloud environment that supports Heat,
 follow the :doc:`heat-dev-env`.
 
-If developing Kolla on a system that provides VirtualBox or Libvirt in
-addition to Vagrant, use the Vagrant virtual environment documented in
+If developing Kolla on a system that provides VirtualBox or Libvirt in addition
+to Vagrant, use the Vagrant virtual environment documented in
 :doc:`vagrant-dev-env`.
 
-Currently the Heat development environment is entirely non-functional.
-The Kolla core reviewers have debated removing it from the repository
-but have resisted to provide an opportunity for contributors to make Heat
-usable for Kolla development.  THe Kolla core reviewers believe Heat
-would offer a great way to develop Kolla in addition to Vagrant,
-bare metal, or a manually setup virtual machine.
+Currently the Heat development environment is entirely non-functional. The
+Kolla core reviewers have debated removing it from the repository but have
+resisted to provide an opportunity for contributors to make Heat usable for
+Kolla development. The Kolla core reviewers believe Heat would offer a great
+way to develop Kolla in addition to Vagrant, bare metal, or a manually setup
+virtual machine.
 
 For more information refer to
 `_bug 1562334 <https://bugs.launchpad.net/kolla/+bug/1562334>`__.
@@ -337,8 +337,8 @@ Note ``--base`` and ``--type`` can be added to the above ``kolla-build``
 command if different distributions or types are desired.
 
 It is also possible to build individual containers. As an example, if the
-glance containers failed to build, all glance related containers can be
-rebuilt as follows:
+glance containers failed to build, all glance related containers can be rebuilt
+as follows:
 
 ::
 
@@ -358,13 +358,13 @@ instruction in :doc:`image-building`.
 Deploying Kolla
 ===============
 
-The Kolla community provides two example methods of Kolla
-deploy: *all-in-one* and *multinode*. The "all-in-one" deploy is similar
-to `devstack <http://docs.openstack.org/developer/devstack/>`__ deploy which
-installs all OpenStack services on a single host. In the "multinode" deploy,
+The Kolla community provides two example methods of Kolla deploy: *all-in-one*
+and *multinode*. The *all-in-one* deploy is similar to
+`devstack <http://docs.openstack.org/developer/devstack/>`__ deploy which
+installs all OpenStack services on a single host. In the *multinode* deploy,
 OpenStack services can be run on specific hosts. This documentation only
-describes deploying *all-in-one* method as most simple one. To setup multinode
-see the :doc:`multinode`.
+describes deploying *all-in-one* method as most simple one. To setup
+*multinode* see the :doc:`multinode`.
 
 Each method is represented as an Ansible inventory file. More information on
 the Ansible inventory file can be found in the Ansible `inventory introduction
@@ -374,15 +374,15 @@ All variables for the environment can be specified in the files:
 ``/etc/kolla/globals.yml`` and ``/etc/kolla/passwords.yml``.
 
 Generate passwords for ``/etc/kolla/passwords.yml`` using the provided
-``kolla-genpwd`` tool.  The tool will populate all empty fields in the
+``kolla-genpwd`` tool. The tool will populate all empty fields in the
 ``/etc/kolla/passwords.yml`` file using randomly generated values to secure the
-deployment.  Optionally, the passwords may be populate in the file by hand.
+deployment. Optionally, the passwords may be populate in the file by hand.
 
 ::
 
     kolla-genpwd
 
-Start by editing /etc/kolla/globals.yml. Check and edit, if needed, these
+Start by editing ``/etc/kolla/globals.yml``. Check and edit, if needed, these
 parameters: ``kolla_base_distro``, ``kolla_install_type``. These parameters
 should match what you used in the ``kolla-build`` command line. The default for
 ``kolla_base_distro`` is ``centos`` and for ``kolla_install_type`` is ``binary``.
@@ -396,23 +396,22 @@ sure ``globals.yml`` has the following entries:
 
 
 Please specify an unused IP address in the network to act as a VIP for
-``kolla_internal_vip_address``. The VIP will be used with keepalived and
-added to the ``api_interface`` as specified in the ``globals.yml`` ::
+``kolla_internal_vip_address``. The VIP will be used with keepalived and added
+to the ``api_interface`` as specified in the ``globals.yml`` ::
 
     kolla_internal_vip_address: "10.10.10.254"
 
 The ``network_interface`` variable is the interface to which Kolla binds API
-services. For example, when starting up Mariadb it will bind to the
-IP on the interface list in the ``network_interface`` variable. ::
+services. For example, when starting up Mariadb it will bind to the IP on the
+interface list in the ``network_interface`` variable. ::
 
     network_interface: "eth0"
 
-The ``neutron_external_interface`` variable is the interface that will
-be used for the external bridge in Neutron. Without this bridge the deployment
-instance traffic will be unable to access the rest of the Internet. In
-the case of a single interface on a machine, a veth pair may be used where
-one end of the veth pair is listed here and the other end is in a bridge on
-the system. ::
+The ``neutron_external_interface`` variable is the interface that will be used
+for the external bridge in Neutron. Without this bridge the deployment instance
+traffic will be unable to access the rest of the Internet. In the case of a
+single interface on a machine, a veth pair may be used where one end of the
+veth pair is listed here and the other end is in a bridge on the system. ::
 
     neutron_external_interface: "eth1"
 
@@ -511,22 +510,21 @@ environment with a glance image and neutron networks:
 Failures
 ========
 
-Nearly always when Kolla fails, it is caused by a CTRL-C during the
-deployment process or a problem in the ``globals.yml`` configuration.
+Nearly always when Kolla fails, it is caused by a CTRL-C during the deployment
+process or a problem in the ``globals.yml`` configuration.
 
-To correct the problem where Operators have a misconfigured
-environment, the Kolla developers have added a precheck feature which
-ensures the deployment targets are in a state where Kolla may deploy
-to them.  To run the prechecks, execute:
+To correct the problem where Operators have a misconfigured environment, the
+Kolla developers have added a precheck feature which ensures the deployment
+targets are in a state where Kolla may deploy to them. To run the prechecks,
+execute:
 
 ::
 
     kolla-ansible prechecks
 
-If a failure during deployment occurs it nearly always occurs during
-evaluation of the software.  Once the Operator learns the few
-configuration options required, it is highly unlikely they will experience
-a failure in deployment.
+If a failure during deployment occurs it nearly always occurs during evaluation
+of the software. Once the Operator learns the few configuration options
+required, it is highly unlikely they will experience a failure in deployment.
 
 Deployment may be run as many times as desired, but if a failure in a
 bootstrap task occurs, a further deploy action will not correct the problem.
@@ -542,14 +540,14 @@ On each node where OpenStack is deployed run:
     tools/cleanup-containers
     tools/cleanup-host
 
-The Operator will have to copy via scp or some other means the cleanup
-scripts to the various nodes where the failed containers are located.
+The Operator will have to copy via scp or some other means the cleanup scripts
+to the various nodes where the failed containers are located.
 
 Any time the tags of a release change, it is possible that the container
-implementation from older versions won't match the Ansible playbooks in
-a new version.  If running multinode from a registry, each node's Docker
-image cache must be refreshed with the latest images before a new deployment
-can occur.  To refresh the docker cache from the local Docker registry:
+implementation from older versions won't match the Ansible playbooks in a new
+version. If running multinode from a registry, each node's Docker image cache
+must be refreshed with the latest images before a new deployment can occur. To
+refresh the docker cache from the local Docker registry:
 
 ::
 
@@ -575,7 +573,7 @@ The logs can be examined by executing:
     docker exec -it heka bash
 
 The logs from all services in all containers may be read from
-/var/log/kolla/SERVICE_NAME
+``/var/log/kolla/SERVICE_NAME``
 
 If the stdout logs are needed, please run: