Run pandoc to convert the documentation

This converts all MD formatted docs that were renamed to RST to
preserve git history into actual RST documentation.  Some minor
edits were made but in general the purpose of this patch is to
*only* convert the documentation not rework the documentation.
I do plan on reworking the documentation in further patch sets.

All links were tested and a test rendering is available:

    http://github.com/sdake/kolla

Change-Id: I3df430b14df1ede15407c7f4ba7afcbdc6f9d757

4 files changed, 224 insertions, 154 deletions

diff --git a/docs/ansible-deployment.rst b/docs/ansible-deployment.rst
index 9f277c2ab..37a08a98a 100644
--- a/docs/ansible-deployment.rst
+++ b/docs/ansible-deployment.rst
@@ -1,95 +1,111 @@
 Kolla with Ansible!
-============================
-
-Kolla supports deploying Openstack using [Ansible][].
-
-[Ansible]: https://docs.ansible.com
+===================
 
+Kolla supports deploying Openstack using
+`Ansible <https://docs.ansible.com>`__.
 
 Getting Started
 ---------------
 
 To run the Ansible playbooks, an inventory file which tracks all of the
-available nodes in the environment must be speficied. With this inventory file
-Ansible will log into each node via ssh (configurable) and run tasks. Ansible
-does not require password-less logins via ssh, however it is highly recommended
-to setup ssh-keys.
-
-Two sample inventory files are provided, *all-in-one*, and *multinode*. The
-"all-in-one" inventory defaults to use the Ansible "local" connection type,
-which removes the need to setup ssh keys in order to get started quickly.
+available nodes in the environment must be specified. With this
+inventory file Ansible will log into each node via ssh (configurable)
+and run tasks. Ansible does not require password-less logins via ssh,
+however it is highly recommended to setup ssh-keys.
 
-More information on the Ansible inventory file can be found [here][].
+Two sample inventory files are provided, *all-in-one*, and *multinode*.
+The "all-in-one" inventory defaults to use the Ansible "local"
+connection type, which removes the need to setup ssh keys in order to
+get started quickly.
 
-[here]: https://docs.ansible.com/intro_inventory.html
+More information on the Ansible inventory file can be found in the Ansible
+`inventory introduction <https://docs.ansible.com/intro_inventory.html>`__.
 
 Prerequisites
 -------------
 
-On the deployment host you must have Ansible>=1.8.4 installed. That is the only
-requirement for deploying. To build the images locally you must also have the
-Python library docker-py>=1.2.0 installed.
+On the deployment host you must have Ansible>=1.8.4 installed. That is
+the only requirement for deploying. To build the images locally you must
+also have the Python library docker-py>=1.2.0 installed.
 
-On the target nodes you must have docker>=1.6.0 and docker-py>=1.2.0 installed.
+On the target nodes you must have docker>=1.6.0 and docker-py>=1.2.0
+installed.
 
 Deploying
 ---------
 
-Add the etc/kolla directory to /etc/kolla on the deployment host. Inside of
-this directory are two files and a minimum number of parameters which are
-listed below.
+Add the etc/kolla directory to /etc/kolla on the deployment host. Inside
+of this directory are two files and a minimum number of parameters which
+are listed below.
 
 All variables for the environment can be specified in the files:
 "/etc/kolla/globals.yml" and "/etc/kolla/passwords.yml"
 
-The kolla_*_address variables can both be the same. Please specify an unused IP
-address in your network to act as a VIP for kolla_internal_address. The VIP will
-be used with keepalived and added to your "api_interface" as specified in the
-globals.yml
+The kolla\_\*\_address variables can both be the same. Please specify
+an unused IP address in your network to act as a VIP for
+kolla\_internal\_address. The VIP will be used with keepalived and
+added to your "api\_interface" as specified in the globals.yml
+
+::
 
     kolla_external_address: "openstack.example.com"
     kolla_internal_address: "10.10.10.254"
 
-The "network_interface" variable is the interface that we bind all our services
-to. For example, when starting up Mariadb it will bind to the IP on the
-interface list in the "network_interface" variable.
+The "network\_interface" variable is the interface that we bind all our
+services to. 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
-your external bridge in Neutron. Without this bridge your instance traffic will
-be unable to access the rest of the Internet. In the case of a single interface
-on a machine, you may use a veth pair where one end of the veth pair is listed
-here and the other end is in a bridge on your system.
+The "neutron\_external\_interface" variable is the interface that will
+be used for your external bridge in Neutron. Without this bridge your
+instance traffic will be unable to access the rest of the Internet. In
+the case of a single interface on a machine, you may use a veth pair
+where one end of the veth pair is listed here and the other end is in a
+bridge on your system.
+
+::
 
     neutron_external_interface: "eth1"
 
-The docker_pull_policy specifies whether Docker should always pull images from
-the repository it is configured for, or only in the case where the image isn't
-present locally. If you are building your own images locally without pushing
-them to the Docker Registry, or a local registry, you must set this value to
-"missing" or when you run the playbooks docker will attempt to fetch the latest
-image upstream.
+The docker\_pull\_policy specifies whether Docker should always pull
+images from the repository it is configured for, or only in the case
+where the image isn't present locally. If you are building your own
+images locally without pushing them to the Docker Registry, or a local
+registry, you must set this value to "missing" or when you run the
+playbooks docker will attempt to fetch the latest image upstream.
+
+::
 
     docker_pull_policy: "always"
 
-For All-In-One deploys, the following commands can be run. These will setup all
-of the containers on the localhost. These commands will be wrapped in the
-kolla-script in the future.
+For All-In-One deploys, the following commands can be run. These will
+setup all of the containers on the localhost. These commands will be
+wrapped in the kolla-script in the future.
+
+::
 
     cd ./kolla/ansible
     ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml
 
-To run the playbooks for only a particular service, Ansible tags can be used.
-Multiple tags may be specified, and order is still determined by the playbooks.
+To run the playbooks for only a particular service, Ansible tags can be
+used. Multiple tags may be specified, and order is still determined by
+the playbooks.
+
+::
 
     cd ./kolla/ansible
     ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml --tags rabbitmq
     ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml --tags rabbitmq,mariadb
 
-Finally, you can view ./kolla/tools/openrc-example for an example of an openrc
-you can use with your environment. If you wish you may also run the following
-command to initiate your environment with an glance image and neutron networks.
+Finally, you can view ./kolla/tools/openrc-example for an example of an
+openrc you can use with your environment. If you wish you may also run
+the following command to initiate your environment with an glance image
+and neutron networks.
+
+::
 
     cd ./kolla/tools
     ./init-runonce
@@ -97,6 +113,5 @@ command to initiate your environment with an glance image and neutron networks.
 Further Reading
 ---------------
 
-Ansible playbook documentation can be found [here][].
-
-[here]: http://docs.ansible.com/playbooks.html
+Ansible playbook documentation can be found in the Ansible
+`playbook documentation <http://docs.ansible.com/playbooks.html>`__.
diff --git a/docs/dev-quickstart.rst b/docs/dev-quickstart.rst
index 2b79097e4..e5cecf53d 100644
--- a/docs/dev-quickstart.rst
+++ b/docs/dev-quickstart.rst
@@ -1,76 +1,92 @@
-# Developer Environment
+Developer Environment
+=====================
 
 If you are developing Kolla on an existing OpenStack cloud that supports
-Heat, then follow the Heat template [README][].  Another option available
-on systems with VirutalBox is the use of [Vagrant][].
+Heat, then follow the Heat template
+`README <https://github.com/stackforge/kolla/blob/master/devenv/README.md>`__.
+Another option available on systems with VirutalBox is the use of
+`Vagrant <https://github.com/stackforge/kolla/blob/master/docs/vagrant.md>`__.
 
 The best experience is available with bare metal deployment by following
 the instructions below to manually create your Kolla deployment.
 
-[README]: https://github.com/stackforge/kolla/blob/master/devenv/README.md
-[Vagrant]: https://github.com/stackforge/kolla/blob/master/docs/vagrant.md
+Installing Dependencies
+-----------------------
 
-## Installing Dependencies
-
-NB: Kolla will not run on Fedora 22 or later.  Fedora 22 compresses kernel
-modules with the .xz compressed format.  The guestfs system cannot read
-these images because a dependent package supermin in CentOS needs to be
-updated to add .xz compressed format support.
+NB: Kolla will not run on Fedora 22 or later. Fedora 22 compresses
+kernel modules with the .xz compressed format. The guestfs system cannot
+read these images because a dependent package supermin in CentOS needs
+to be updated to add .xz compressed format support.
 
 To install Kolla depenedencies use:
 
+::
+
     git clone http://github.com/stackforge/kolla
     cd kolla
     sudo pip install -r requirements.txt
 
-In order to run Kolla, it is mandatory to run a version of `docker` that is
-1.7.0 or later.
+In order to run Kolla, it is mandatory to run a version of ``docker``
+that is 1.7.0 or later.
+
+For most systems you can install the latest stable version of Docker
+with the following command:
 
-For most systems you can install the latest stable version of Docker with the
-following command:
+::
 
     curl -sSL https://get.docker.io | bash
 
-For Ubuntu based systems, do not use AUFS when starting Docker daemon unless
-you are running the Utopic (3.19) kernel. AUFS requires CONFIG_AUFS_XATTR=y
-set when building the kernel. On Ubuntu, versions prior to 3.19 did not set that
-flag. If you are unable to upgrade your kernel, you should use a different
-storage backend such as btrfs.
+For Ubuntu based systems, do not use AUFS when starting Docker daemon
+unless you are running the Utopic (3.19) kernel. AUFS requires
+CONFIG\_AUFS\_XATTR=y set when building the kernel. On Ubuntu, versions
+prior to 3.19 did not set that flag. If you are unable to upgrade your
+kernel, you should use a different storage backend such as btrfs.
 
 Next, install the OpenStack python clients if they are not installed:
 
+::
+
     sudo pip install -U python-openstackclient
 
-Finally stop libvirt on the host machine.  Only one copy of libvirt may be
-running at a time.
+Finally stop libvirt on the host machine. Only one copy of libvirt may
+be running at a time.
 
-    service libvirtd stop
+::
 
-The basic starting environment will be created using `ansible`.
-This environment will start up the OpenStack services listed in the
-inventory file.
+    service libvirtd stop
 
-## Starting Kolla
+The basic starting environment will be created using ``ansible``. This
+environment will start up the OpenStack services listed in the inventory
+file.
 
-Configure Ansible by reading the Kolla Ansible configuration documentation
-[DEPLOY][].
+Starting Kolla
+--------------
 
-[DEPLOY]: https://github.com/stackforge/kolla/blob/master/docs/ansible-deployment.md
+Configure Ansible by reading the Kolla
+`Ansible configuration <https://github.com/stackforge/kolla/blob/master/docs/ansible-deployment.md>`__ documentation.
 
 Next, run the start command:
 
+::
+
     $ sudo ./tools/kolla-ansible deploy
 
-A bare metal system takes three minutes to deploy AIO.  A virtual machine
-takes five minutes to deploy AIO.  These are estimates; your hardware may
+A bare metal system takes three minutes to deploy AIO. A virtual machine
+takes five minutes to deploy AIO. These are estimates; your hardware may
 be faster or slower but should near these results.
 
-## Debugging Kolla
+Debugging Kolla
+---------------
 
 You can determine a container's status by executing:
 
+::
+
     $ sudo docker ps -a
 
 If any of the containers exited you can check the logs by executing:
 
+::
+
     $ sudo docker logs <container-name>
+
diff --git a/docs/image-building.rst b/docs/image-building.rst
index a67f3da08..48b3ce2f2 100644
--- a/docs/image-building.rst
+++ b/docs/image-building.rst
@@ -1,77 +1,101 @@
-# Image building
+Image building
+==============
 
-The `tools/build-docker-image` script in this repository is
-responsible for building docker images.  It is symlinked as `./build`
+The ``tools/build-docker-image`` script in this repository is
+responsible for building docker images. It is symlinked as ``./build``
 inside each Docker image directory.
 
 When creating new image directories, you can run the
-`tools/update-build-links` scripts to install the `build` symlink
+``tools/update-build-links`` scripts to install the ``build`` symlink
 (this script will install the symlink anywhere it find a file named
-`Dockerfile`).
+``Dockerfile``).
 
-## Workflow
+Workflow
+--------
 
 In general, you will build images like this:
 
+::
+
     $ cd docker/keystone
     $ ./build
 
 By default, the above command would build
-`kollaglue/centos-rdo-keystone:CID`, where `CID` is the current short
-commit ID.  That is, given:
+``kollaglue/centos-rdo-keystone:CID``, where ``CID`` is the current
+short commit ID. That is, given:
+
+::
 
     $ git rev-parse HEAD
     76a16029006a2f5d3b79f1198d81acb6653110e9
 
 The above command would generate
-`kollaglue/centos-rdo-keystone:76a1602`.  This tagging is meant to
+``kollaglue/centos-rdo-keystone:76a1602``. This tagging is meant to
 prevent developers from stepping on each other or on release images
 during the development process.
 
-To push the image after building, add `--push`:
+To push the image after building, add ``--push``:
+
+::
 
     $ ./build --push
 
-To use these images, you must specify the tag in your `docker run`
+To use these images, you must specify the tag in your ``docker run``
 commands:
 
+::
+
     $ docker run kollaglue/centos-rdo-keystone:76a1602
 
-## Building releases
+Building releases
+-----------------
+
+To build into the ``latest`` tag, add ``--release``:
 
-To build into the `latest` tag, add `--release`:
+::
 
     $ ./build --release
 
 Or to build and push:
 
+::
+
     $ ./build --push --release
 
-## Build all images at once
+Build all images at once
+------------------------
+
+The ``build-all-docker-images`` script in the tools directory is a
+wrapper for the ``build-docker-image`` that builds all images, as the
+name suggests, in the correct order. It responds to the same options as
+``build-docker-image`` with the additional ``--from`` and ``--to``
+options that allows building only images that have changed between the
+specified git revisions.
 
-The `build-all-docker-images` script in the tools directory is a wrapper for
-the `build-docker-image` that builds all images, as the name suggests, in the
-correct order. It responds to the same options as `build-docker-image` with the
-additional `--from` and `--to` options that allows building only images that
-have changed between the specified git revisions.
+For example, to build all images contained in docker directory and push
+new release:
 
-For example, to build all images contained in docker directory and push new release:
+::
 
     $ tools/build-all-docker-images --release --push
 
 To build only images modified in test-branch along with their children:
 
+::
+
     $ tools/build-all-docker-images --from master --to test-branch
 
-## Configuration
+Configuration
+-------------
 
-The `build-docker-image` script will look for a file named `.buildconf`
-in the image directory and in the top level of the repository.  You
-can use this to set defaults, such as:
+The ``build-docker-image`` script will look for a file named
+``.buildconf`` in the image directory and in the top level of the
+repository. You can use this to set defaults, such as:
+
+::
 
     NAMESPACE=larsks
     PREFIX=fedora-rdo-
 
-This setting would cause images to be tagged into the `larsks/`
+This setting would cause images to be tagged into the ``larsks/``
 namespace and use Fedora as base image instead of the default CentOS.
-
diff --git a/docs/vagrant.rst b/docs/vagrant.rst
index b6f47f179..f3fe559aa 100644
--- a/docs/vagrant.rst
+++ b/docs/vagrant.rst
@@ -1,81 +1,96 @@
 Vagrant up!
-============================
+===========
 
-This guide describes how to use [Vagrant][] to assist in developing for Kolla.
-
-Vagrant is a tool to assist in scripted creation of virtual machines, it will
-take care of setting up a CentOS-based cluster of virtual machines, each with
-proper hardware like memory amount and number of network interfaces.
-
-[Vagrant]: http://vagrantup.com
+This guide describes how to use `Vagrant <http://vagrantup.com>`__ to
+assist in developing for Kolla.
 
+Vagrant is a tool to assist in scripted creation of virtual machines, it
+will take care of setting up a CentOS-based cluster of virtual machines,
+each with proper hardware like memory amount and number of network
+interfaces.
 
 Getting Started
 ---------------
 
 The vagrant setup will build a cluster with the following nodes:
 
-- 3 control nodes
-- 1 compute node
-- 1 operator node
+-  3 control nodes
+-  1 compute node
+-  1 operator node
+
+Kolla runs from the operator node to deploy OpenStack on the other
+nodes.
 
-Kolla runs from the operator node to deploy OpenStack on the other nodes.
+All nodes are connected with each other on the secondary nic, the
+primary nic is behind a NAT interface for connecting with the internet.
+A third nic is connected without IP configuration to a public bridge
+interface. This may be used for Neutron/Nova to connect to instances.
 
-All nodes are connected with each other on the secondary nic, the primary nic
-is behind a NAT interface for connecting with the internet. A third nic is
-connected without IP configuration to a public bridge interface. This may be
-used for Neutron/Nova to connect to instances.
+Start with downloading and installing the Vagrant package for your
+distro of choice. Various downloads can be found
+at the `Vagrant downloads <https://www.vagrantup.com/downloads.html>`__.
+After we will install the hostmanager plugin so all hosts are recorded in
+/etc/hosts (inside each vm):
 
-Start with downloading and installing the Vagrant package for your distro of
-choice. Various downloads can be found [here][]. After we will install the
-hostmanager plugin so all hosts are recorded in /etc/hosts (inside each vm):
+::
 
     vagrant plugin install vagrant-hostmanager
 
-Vagrant supports a wide range of virtualization technologies, of which we will
-use VirtualBox for now.
+Vagrant supports a wide range of virtualization technologies, of which
+we will use VirtualBox for now.
 
-Find some place in your homedir and checkout the Kolla repo
+Find some place in your homedir and checkout the Kolla repo:
+
+::
 
     git clone https://github.com/stackforge/kolla.git ~/dev/kolla
 
-You can now tweak the Vagrantfile or start a CentOS7-based cluster right away:
+You can now tweak the Vagrantfile or start a CentOS7-based cluster right
+away:
 
-    cd ~/dev/kolla/vagrant && vagrant up
+::
 
-The command `vagrant up` will build your cluster, `vagrant status` will give
-you a quick overview once done.
+    cd ~/dev/kolla/vagrant && vagrant up
 
-[here]: https://www.vagrantup.com/downloads.html
+The command ``vagrant up`` will build your cluster, ``vagrant status``
+will give you a quick overview once done.
 
 Vagrant Up
----------
+----------
+
+Once vagrant has completed deploying all nodes, we can focus on
+launching Kolla. First, connect with the *operator* node:
 
-Once vagrant has completed deploying all nodes, we can focus on launching Kolla.
-First, connect with the _operator_ node:
+::
 
     vagrant ssh operator
 
-Once connected you can run a simple Ansible-style ping to verify if the cluster is operable:
+Once connected you can run a simple Ansible-style ping to verify if the
+cluster is operable:
+
+::
 
     ansible -i kolla/ansible/inventory/multinode all -m ping -e ansible_ssh_user=root
 
-Congratulations, your cluster is usable and you can start deploying OpenStack using Ansible!
+Congratulations, your cluster is usable and you can start deploying
+OpenStack using Ansible!
 
-To speed things up, there is a local registry running on the operator. All nodes are configured
-so they can use this insecure repo to pull from, and they will use it as mirror. Ansible may
-use this registry to pull images from.
+To speed things up, there is a local registry running on the operator.
+All nodes are configured so they can use this insecure repo to pull
+from, and they will use it as mirror. Ansible may use this registry to
+pull images from.
 
-All nodes have a local folder shared between the group and the hypervisor, and a folder shared
-between _all_ nodes and the hypervisor. This mapping is lost after reboots, so make sure you use
-the command `vagrant reload <node>` when reboots are required. Having this shared folder you
-have a method to supply a different docker binary to the cluster. The shared folder is also
-used to store the docker-registry files, so they are save from destructive operations like
-`vagrant destroy`.
+All nodes have a local folder shared between the group and the
+hypervisor, and a folder shared between *all* nodes and the hypervisor.
+This mapping is lost after reboots, so make sure you use the command
+``vagrant reload <node>`` when reboots are required. Having this shared
+folder you have a method to supply a different docker binary to the
+cluster. The shared folder is also used to store the docker-registry
+files, so they are save from destructive operations like
+``vagrant destroy``.
 
 Further Reading
 ---------------
 
-All Vagrant documentation can be found on their [website][].
-
-[website]: http://docs.vagrantup.com
+All Vagrant documentation can be found at
+`docs.vagrantup.com <http://docs.vagrantup.com>`__.