Merge "Run pandoc to convert the documentation"

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>`__.