Add doc8 test and improve rst syntax

This will test all rst files inside the doc directory for style issues with
doc8 (an opinionated style checker for rst styles of documentation).

This will fix all syntax issues identified by doc8 and will improve
the syntax.

Change-Id: Id1b9563e07e77e306aef5a0767c98c27f87c5c0e

doc/CONTRIBUTING.rst

@@ -7,16 +7,16 @@ How To Contribute
 Basics
 ======
 
-#. Our source code is hosted on `OpenStack GitHub`_, but pull requests submitted
+#. Our source code is hosted on `OpenStack GitHub`_, but pull requests
-   through GitHub will be ignored. Bugs should be filed on launchpad_,
+   submitted through GitHub will be ignored. Bugs should be filed on
-   not GitHub.
+   launchpad_, not GitHub.
 
 #. Please follow OpenStack `Gerrit Workflow`_ to to contribute to Kolla.
 
 #. Note the branch you're proposing changes to. ``master`` is the current focus
    of development. Kolla project has a strict policy of only allowing backports
-   in ``stable/branch``, unless when not applicable. A bug in a ``stable/branch``
+   in ``stable/branch``, unless when not applicable. A bug in a
-   will first have to be fixed in ``master``.
+   ``stable/branch`` will first have to be fixed in ``master``.
 
 #. Please file a launchpad_ blueprint for any significant code change and a bug
    for any significant bug fix or add a TrivialFix tag for simple changes.
@@ -33,6 +33,6 @@ Development Environment
 =======================
 
 #. Please follow our `quickstart`_ to deploy your environment and test your
-  changes.
+   changes.
 
 .. _quickstart: http://docs.openstack.org/developer/kolla/quickstart.html

doc/advanced-configuration.rst

@@ -67,7 +67,7 @@ TLS protection for the external VIP.  TLS allows a client to authenticate
 the OpenStack service endpoint and allows for encryption of the requests
 and responses.
 
-.. NOTE:: The kolla_internal_vip_address and kolla_external_vip_address must
+.. note:: The kolla_internal_vip_address and kolla_external_vip_address must
    be different to enable TLS on the external network.
 
 The configuration variables that control TLS networking are:
@@ -83,7 +83,7 @@ The default for TLS is disabled; to enable TLS networking:
     kolla_external_fqdn_cert: "{{ node_config_directory }}/certificates/mycert.pem"
 
 
-.. NOTE:: TLS authentication is based on certificates that have been
+.. note:: TLS authentication is based on certificates that have been
    signed by trusted Certificate Authorities.  Examples of commercial
    CAs are Comodo, Symantec, GoDaddy, and GlobalSign.  Letsencrypt.org
    is a CA that will provide trusted certificates at no charge. Many
@@ -119,7 +119,7 @@ have settings similar to this:
 Self-Signed Certificates
 ========================
 
-.. NOTE:: Self-signed certificates should never be used in production.
+.. note:: Self-signed certificates should never be used in production.
 
 It is not always practical to get a certificate signed by a well-known
 trust CA, for example a development or internal test kolla deployment.  In
@@ -144,18 +144,19 @@ TODO(all) fill this section out
 OpenStack Service Configuration in Kolla
 ========================================
 
-.. NOTE:: As of now kolla only supports config overrides for ini based configs.
+.. note:: As of now kolla only supports config overrides for ini based configs.
-An operator can change the location where custom config files are read from by
+          An operator can change the location where custom config files are read
-editing ``/etc/kolla/globals.yml`` and adding the following line.
+          from by editing ``/etc/kolla/globals.yml`` and adding the following
+          line.
 
 ::
 
    # The directory to merge custom config files the kolla's config files
    node_custom_config: "/etc/kolla/config"
 
-Kolla allows the operator to override configuration of services. Kolla will look
+Kolla allows the operator to override configuration of services. Kolla will
-for a file in ``/etc/kolla/config/<< sevice name >>/<< config file >>``. This
+look for a file in ``/etc/kolla/config/<< sevice name >>/<< config file >>``.
-can be done per-project, per-service or per-service-on-specified-host.
+This can be done per-project, per-service or per-service-on-specified-host.
 For example to override scheduler_max_attempts in nova scheduler, the operator
 needs to create ``/etc/kolla/config/nova/nova-scheduler.conf`` with content:
 
@@ -173,8 +174,8 @@ on host myhost, the operator needs to create file
    [DEFAULT]
    ram_allocation_ratio = 5.0
 
-The operator can make these changes after services were already deployed by using
+The operator can make these changes after services were already deployed by
-following command:
+using following command:
 
 ::
 

doc/ceph-guide.rst

@@ -74,8 +74,8 @@ RGW requires a healthy cluster in order to be successfully deployed. On initial
 start up, RGW will create several pools. The first pool should be in an
 operational state to proceed with the second one, and so on. So, in the case of
 an **all-in-one** deployment, it is necessary to change the default number of
-copies for the pools before deployment. Modify the file ``/etc/kolla/config/ceph.conf``
+copies for the pools before deployment. Modify the file
-and add the contents::
+``/etc/kolla/config/ceph.conf`` and add the contents::
 
     [global]
     osd pool default size = 1
@@ -129,8 +129,8 @@ must make the choice to use an erasure coded pool or a replicated pool
 (the default) when you initially deploy. You cannot change this without
 completely removing the pool and recreating it.
 
-To enable erasure coded pools add the following options to your ``/etc/kolla/globals.yml``
+To enable erasure coded pools add the following options to your
-configuration file:
+``/etc/kolla/globals.yml`` configuration file:
 
 ::
 
@@ -189,8 +189,8 @@ The default pool Ceph creates is named **rbd**. It is safe to remove this pool:
 Troubleshooting
 ===============
 
-Deploy fails during 'Fetching Ceph keyrings ... No JSON object could be decoded'
+Deploy fails with 'Fetching Ceph keyrings ... No JSON object could be decoded'
---------------------------------------------------------------------------------
+------------------------------------------------------------------------------
 
 If an initial deploy of Ceph fails, perhaps due to improper configuration or
 similar, the cluster will be partially formed and will need to be reset for a

doc/cinder-guide.rst

@@ -25,7 +25,7 @@ a real physical volume or a loopback mounted file for development.
   present is via a Ceph deployment.  If community members disagree
   with this decision, please report the specific use case in the
   Cinder bug tracker here:
-    `_bug 1571211  <https://launchpad.net/bugs/1571211>`__.
+  `_bug 1571211  <https://launchpad.net/bugs/1571211>`__.
 
 
 Create a Volume Group

doc/external-ceph-guide.rst

@@ -14,7 +14,7 @@ Requirements
 * An existing installation of Ceph
 * Existing Ceph storage pools
 * Existing credentials in Ceph for OpenStack services to connect to Ceph
-(Glance, Cinder, Nova)
+  (Glance, Cinder, Nova)
 
 Enabling External Ceph
 ======================
@@ -166,7 +166,9 @@ Put ceph.conf and keyring file into ``/etc/kolla/config/nova``:
   $ ls /etc/kolla/config/nova
   ceph.client.nova.keyring  ceph.conf
 
-Configure nova-compute to use Ceph as the ephemeral backend by creating ``/etc/kolla/config/nova/nova-compute.conf`` and adding the following contents:
+Configure nova-compute to use Ceph as the ephemeral backend by creating
+``/etc/kolla/config/nova/nova-compute.conf`` and adding the following
+contents:
 
 ::
 
@@ -176,4 +178,4 @@ Configure nova-compute to use Ceph as the ephemeral backend by creating ``/etc/k
   images_rbd_ceph_conf=/etc/ceph/ceph.conf
   rbd_user=nova
 
-NOTE: rbd_user might vary depending on your environment.
+.. note:: ``rbd_user`` might vary depending on your environment.

doc/heat-dev-env.rst

@@ -89,12 +89,14 @@ The container\_external\_subnet\_id: is the subnet equivalent to
 container\_external\_network\_id
 
 Review the parameters section of kollacluster.yaml for a full list of
-configuration options. **Note:** You must provide values for:
+configuration options.
 
--  ``ssh_key_name``
+.. note:: You must provide values for:
--  ``external_network_id``
+
--  ``container_external_network_id``
+          -  ``ssh_key_name``
--  ``container_external_subnet_id``
+          -  ``external_network_id``
+          -  ``container_external_network_id``
+          -  ``container_external_subnet_id``
 
 And then create the stack, referencing that environment file:
 

doc/image-building.rst

@@ -19,6 +19,7 @@ Install tox and generate the build configuration. The build configuration is
 designed to hold advanced customizations when building containers.
 
 Create kolla-build.conf using the following steps.
+
 ::
 
     pip install tox
@@ -59,7 +60,7 @@ command line::
     kolla-build keystone
 
 In this case, the build script builds all images which name contains the
-*keystone* string along with their dependencies.
+``keystone`` string along with their dependencies.
 
 Multiple names may be specified on the command line::
 
@@ -85,7 +86,7 @@ command::
 
     tox -e genconfig
 
-Build OpenStack from Source
+Build OpenStack from source
 ===========================
 
 When building images, there are two methods of the OpenStack install. One is
@@ -112,7 +113,7 @@ the best use of the docker cache.
     [keystone]
     type = git
     location = https://github.com/openstack/keystone
-    reference = stable/kilo
+    reference = stable/mitaka
 
     [heat-base]
     type = local
@@ -122,11 +123,13 @@ the best use of the docker cache.
     type = local
     location = /tmp/ironic.tar.gz
 
-To build RHEL containers, it is necessary to use the -i (include header)
+To build RHEL containers, it is necessary to use the ``-i`` (include header)
 feature to include registration with RHN of the container runtime operating
 system. To obtain a RHN username/password/pool id, contact Red Hat.
 
-First create a file called rhel-include::
+First create a file called ``rhel-include``:
+
+::
 
     RUN subscription-manager register --user=<user-name> --password=<password> \
     && subscription-manager attach --pool <pool-id>
@@ -140,13 +143,13 @@ Custom Repos
 
 The build method allows the operator to build containers from custom repos.
 The repos are accepted as a list of comma separated values and can be in
-the form of .repo, .rpm, or a url. See examples below.
+the form of ``.repo``, ``.rpm,`` or a URL. See examples below.
 
-Update rpm_setup_config in ``/etc/kolla/kolla-build.conf``::
+Update ``rpm_setup_config`` in ``/etc/kolla/kolla-build.conf``::
 
     rpm_setup_config = http://trunk.rdoproject.org/centos7/currrent/delorean.repo,http://trunk.rdoproject.org/centos7/delorean-deps.repo
 
-If specifying a .repo file, each .repo file will need to exist in the
+If specifying a ``.repo`` file, each ``.repo`` file will need to exist in the
 same directory as the base Dockerfile (kolla/docker/base)::
 
     rpm_setup_config = epel.repo,delorean.repo,delorean-deps.repo
@@ -187,7 +190,7 @@ image, the operator would add the following block to
 Known issues
 ============
 
-1. Can't build base image because docker fails to install systemd or httpd.
+#. Can't build base image because docker fails to install systemd or httpd.
 
    There are some issues between docker and AUFS. The simple workaround to
    avoid the issue is that add ``-s devicemapper`` or ``-s btrfs`` to
@@ -195,7 +198,7 @@ Known issues
    tracker <https://github.com/docker/docker/issues/6980>`_ and `how to
    configure Docker with BTRFS backend <https://docs.docker.com/engine/userguide/storagedriver/btrfs-driver/#prerequisites>`_.
 
-2. Mirrors are unreliable.
+#. Mirrors are unreliable.
 
    Some of the mirrors Kolla uses can be unreliable. As a result occasionally
    some containers fail to build. To rectify build problems, the build tool
@@ -220,8 +223,8 @@ Running Docker registry is easy. Just use the following command::
    docker run -d -p 4000:5000 --restart=always --name registry \
    -v <local_data_path>:/var/lib/registry registry
 
-Note: ``<local_data_path>`` points to the folder where Docker registry
+.. note:: ``<local_data_path>`` points to the folder where Docker registry
-will store Docker images on the local host.
+          will store Docker images on the local host.
 
 The default port of Docker registry is 5000. But the 5000 port is also the port
 of keystone-api. To avoid conflict, use 4000 port as Docker registry port.

doc/kibana-guide.rst

@@ -31,8 +31,9 @@ following configuration:
 #. Time-field name - Timestamp
 
 After setting parameters, one can create an index with *Create* button.
-Note: This step is necessary until the default Kibana dashboard is implemented
+
-in Kolla.
+.. note:: This step is necessary until the default Kibana dashboard is implemented
+          in Kolla.
 
 Search logs - Discover tab
 ==========================
@@ -63,9 +64,9 @@ generated and previewed. In the menu on the left, metrics for a chart can
 be chosen. The chart can be generated by pressing a green arrow on the top
 of the left-side menu.
 
-NOTE: After creating a visualization, it can be saved by choosing *save
+.. note:: After creating a visualization, it can be saved by choosing *save
-visualization* option in the menu on the right. If it is not saved, it will
+   visualization* option in the menu on the right. If it is not saved, it
-be lost after leaving a page or creating another visualization.
+   will be lost after leaving a page or creating another visualization.
 
 Organize visualizations and searches - Dashboard tab
 ====================================================
@@ -77,9 +78,9 @@ from all saved ones. The order and size of elements can be changed directly
 in this place by moving them or resizing. The color of charts can also be
 changed by checking a colorful dots on the legend near each visualization.
 
-NOTE: After creating a dashboard, it can be saved by choosing *save dashboard*
+.. note:: After creating a dashboard, it can be saved by choosing *save dashboard*
-option in the menu on the right. If it is not saved, it will be lost after
+   option in the menu on the right. If it is not saved, it will be lost after
-leaving a page or creating another dashboard.
+   leaving a page or creating another dashboard.
 
 If a Dashboard has already been saved, it can be opened by choosing *open
 dashboard* option in the menu on the right.

doc/multinode.rst

@@ -24,8 +24,8 @@ with version greater than 2.3, do the following:
 
     docker run -d -p 4000:5000 --restart=always --name registry registry:2
 
-Note: Kolla looks for the Docker registry to use port 4000. (Docker default is
+.. note:: Kolla looks for the Docker registry to use port 4000. (Docker default is
-port 5000)
+          port 5000)
 
 After starting the registry, it is necessary to instruct Docker that it will
 be communicating with an insecure registry. To enable insecure registry
@@ -52,7 +52,7 @@ Edit ``/etc/default/docker`` and add:
     # Ubuntu
     DOCKER_OPTS="--insecure-registry 192.168.1.100:4000"
 
-If ubuntu is using systemd, additional settings needs to be configured. 
+If ubuntu is using systemd, additional settings needs to be configured.
 Copy docker's systemd unit file to ``/etc/systemd/system/`` directory:
 
 ::
@@ -60,7 +60,7 @@ Copy docker's systemd unit file to ``/etc/systemd/system/`` directory:
     # cp /lib/systemd/system/docker.service /etc/systemd/system/docker.service
 
 Next, modify ``/etc/systemd/system/docker.service``, add ``environmentFile``
-variable and add ``$DOCKER_OPTS`` to the end of ExecStart in ``[Service]`` 
+variable and add ``$DOCKER_OPTS`` to the end of ExecStart in ``[Service]``
 section:
 
 ::

doc/operating-kolla.rst

@@ -49,16 +49,16 @@ Then run the command to upgrade::
 
     kolla-ansible upgrade
 
-.. NOTE:: Varying degrees of success have been reported with upgrading
+.. note:: Varying degrees of success have been reported with upgrading
   the libvirt container with a running virtual machine in it. The libvirt
   upgrade still needs a bit more validation, but the Kolla community feels
   confident this mechanism can be used with the correct Docker graph driver.
 
-.. NOTE:: The Kolla community recommends the btrfs or aufs graph drivers for
+.. note:: The Kolla community recommends the btrfs or aufs graph drivers for
   storing data as sometimes the LVM graph driver loses track of its reference
   counting and results in an unremovable container.
 
-.. NOTE:: Because of system technical limitations, upgrade of a libvirt
+.. note:: Because of system technical limitations, upgrade of a libvirt
   container when using software emulation (``virt_driver=qemu`` in nova.conf),
   does not work at all. This is acceptable because KVM is the recommended
   virtualization driver to use with Nova.

doc/quickstart.rst

@@ -16,7 +16,7 @@ The recommended deployment target requirements:
 - At least 8gb main memory
 - At least 40gb disk space.
 
-.. NOTE:: Some commands below may require root permissions (e.g. pip, apt-get).
+.. note:: Some commands below may require root permissions (e.g. pip, apt-get).
 
 Recommended Environment
 =======================
@@ -24,7 +24,8 @@ 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
 started with deploying OpenStack on bare metal or a virtual machine with Kolla.
-There are other deployment environments referenced below in `Additional Environments`_.
+There are other deployment environments referenced below in
+`Additional Environments`_.
 
 Install Dependencies
 ====================
@@ -48,7 +49,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.
 
@@ -61,7 +62,8 @@ Docker Python           1.6.0        none         On target nodes
 Python Jinja2           2.8.0        none         On deployment host
 =====================   ===========  ===========  =========================
 
-Make sure the ``pip`` package manager is installed and upgraded to latest before proceeding:
+Make sure the ``pip`` package manager is installed and upgraded to latest
+before proceeding:
 
 ::
 
@@ -124,17 +126,17 @@ For Ubuntu 14.04 which uses upstart instead of systemd, run the following:
 
     mount --make-shared /run
 
-.. NOTE:: If centos/fedora/oraclelinux container images are built on an Ubuntu
+.. note:: If centos/fedora/oraclelinux container images are built on an Ubuntu
   host, the backend storage driver must not be AUFS (see the known issues in
   :doc:`image-building`).
 
-.. NOTE:: On ubuntu 16.04, please uninstall ``lxd`` and ``lxc`` packages. (issue
+.. note:: On ubuntu 16.04, please uninstall ``lxd`` and ``lxc`` packages. (issue
   with cgroup mounts, mounts exponentially increasing when restarting container).
 
 On the target hosts you also need an updated version of the Docker python
 libraries:
 
-.. NOTE:: The old docker-python is obsoleted by python-docker-py.
+.. note:: The old docker-python is obsoleted by python-docker-py.
 
 ::
 
@@ -402,8 +404,8 @@ deployment. Optionally, the passwords may be populate in the file by hand.
 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``.
+``kolla_base_distro`` is ``centos`` and for ``kolla_install_type`` is
-If you want to use ubuntu with source type, then you should make
+``binary``. If you want to use ubuntu with source type, then you should make
 sure ``globals.yml`` has the following entries:
 
 ::
@@ -479,7 +481,7 @@ In order to see all available parameters, run:
 
     kolla-ansible -h
 
-.. NOTE:: In case of deploying using the _nested_ environment (*eg*.
+.. note:: In case of deploying using the _nested_ environment (*eg*.
   Using Virtualbox VM's, KVM VM's), if your compute node supports
   hardware acceleration for virtual machines.
 
@@ -626,10 +628,10 @@ The values ``<kolla_internal_vip_address>``, ``<kolla_external_vip_address>``
 values are overridden, in ``/etc/kolla/globals.yml``. The value of
 ``<kibana_password>`` can be found in ``/etc/kolla/passwords.yml``.
 
-Note: When you log in to Kibana web interface for the first time, you are
+.. note:: When you log in to Kibana web interface for the first time, you are
-prompted to create an index. Please create an index using the name ``log-*``.
+          prompted to create an index. Please create an index using the name ``log-*``.
-This step is necessary until the default Kibana dashboard is implemented in
+          This step is necessary until the default Kibana dashboard is implemented in
-Kolla.
+          Kolla.
 
 .. _Docker Hub Image Registry: https://hub.docker.com/u/kolla/
 .. _launchpad bug: https://bugs.launchpad.net/kolla/+filebug

doc/security.rst

@@ -34,7 +34,7 @@ Another solution to the persistent data issue is to use a host bind mount which
 involves making, for sake of example, host directory ``var/lib/mysql``
 available inside the container at ``var/lib/mysql``. This absolutely solves the
 problem of persistent data, but it introduces another security issue,
-permissions. With this host bind mount solution the data in ``var/lib/mysql`` 
+permissions. With this host bind mount solution the data in ``var/lib/mysql``
 will be owned by the mysql user in the container. Unfortunately, that mysql
 user in the container could have any UID/GID and thats who will own the data
 outside the container introducing a potential security risk. Additionally, this

doc/vagrant-dev-env.rst

@@ -47,8 +47,8 @@ On Ubuntu 14.04 it is as easy as::
 
     sudo apt-get install vagrant ruby-dev ruby-libvirt python-libvirt libvirt-dev nfs-kernel-server
 
-**Note:** Many distros ship outdated versions of Vagrant by default. When in
+.. note:: Many distros ship outdated versions of Vagrant by default. When in
-doubt, always install the latest from the downloads page above.
+          doubt, always install the latest from the downloads page above.
 
 Next install the hostmanager plugin so all hosts are recorded in ``/etc/hosts``
 (inside each vm)::

test-requirements.txt

@@ -3,6 +3,7 @@
 # process, which may cause wedges in the gate later.
 bandit>=1.0.1 # Apache-2.0
 bashate>=0.2 # Apache-2.0
+doc8  # Apache-2.0
 hacking>=0.10.0
 oslo.log>=1.14.0 # Apache-2.0
 oslotest>=1.10.0 # Apache-2.0

tox.ini

@@ -32,7 +32,9 @@ commands = bandit -r ansible/library dev docker kolla tests tools
 commands = {posargs}
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+commands =
+  doc8 doc
+  python setup.py build_sphinx
 
 [testenv:setupenv]
 commands =