Merge "Upgrade the rst convention of the Contributor Guide"

doc/source/contributor/CONTRIBUTING.rst

@@ -7,37 +7,37 @@ How To Contribute
 Basics
 ======
 
-#. Our source code is hosted on `OpenStack Kolla-Ansible Git`_. Bugs should be
+#. Our source code is hosted on `OpenStack Kolla-Ansible Git
-   filed on launchpad_.
+   <https://git.openstack.org/cgit/openstack/kolla-ansible/>`_. Bugs should be
+   filed on `launchpad <https://bugs.launchpad.net/kolla-ansible>`_.
 
-#. Please follow OpenStack `Gerrit Workflow`_ to contribute to Kolla.
+#. Please follow OpenStack `Gerrit Workflow
+   <https://docs.openstack.org/infra/manual/developers.html#development-workflow>`__
+   to contribute to Kolla-ansible.
 
 #. 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`` will first have to be fixed in ``master``.
 
-#. Please file a launchpad_ blueprint for any significant code change and a bug
+#. Please file a `blueprint of kolla-ansible <https://blueprints.launchpad.net/kolla-ansible>`__
-   for any significant bug fix or add a TrivialFix tag for simple changes.
+   for any significant code change and a bug for any significant bug fix,
-   See how to reference a bug or a blueprint in the commit message here_
+   or add a ``TrivialFix`` tag to commit message for simple changes.
+   See how to reference a bug or a blueprint in the `commit message
+   <https://wiki.openstack.org/wiki/GitCommitMessages>`_.
 
 #. TrivialFix tags or bugs are not required for documentation changes.
 
-.. _OpenStack Kolla-Ansible Git: https://git.openstack.org/cgit/openstack/kolla-ansible/
-.. _launchpad: https://bugs.launchpad.net/kolla-ansible
-.. _here: https://wiki.openstack.org/wiki/GitCommitMessages
-
 Development Environment
 =======================
 
 Please follow our :doc:`/user/quickstart` to deploy your environment and test
 your changes.
 
-Please use the existing sandbox repository, available at
+Please use the existing sandbox repository, available at `sandbox
-https://git.openstack.org/cgit/openstack-dev/sandbox, for learning, understanding
+<https://git.openstack.org/cgit/openstack-dev/sandbox>`_, for learning, understanding
-and testing the `Gerrit Workflow`_.
+and testing the `Gerrit Workflow
-
+<https://docs.openstack.org/infra/manual/developers.html#development-workflow>`_.
-.. _Gerrit Workflow: https://docs.openstack.org/infra/manual/developers.html#development-workflow
 
 Adding a new service
 ====================
@@ -86,12 +86,15 @@ that Kolla uses throughout that should be followed.
     template file in ``ansible/roles/common/templates`` with the following
     content:
 
-    .. code::
+    .. path ansible/roles/common/templates/cron-logrotate-PROJECT.conf.j2
+    .. code-block:: none
 
        "/var/log/kolla/PROJECT/*.log"
        {
        }
 
+    .. end
+
   - For OpenStack services there should be an entry in the ``services`` list
     in the ``cron.json.j2`` template file in ``ansible/roles/common/templates``.
 
@@ -114,7 +117,7 @@ that Kolla uses throughout that should be followed.
 
   - All YAML data files should start with three dashes (``---``).
 
-Other than the above, most roles follow the following pattern:
+Other than the above, most service roles abide by the following pattern:
 
 - ``Register``: Involves registering the service with Keystone, creating
   endpoints, roles, users, etc.

doc/source/contributor/kolla-for-openstack-development.rst

@@ -14,10 +14,10 @@ submitting a patch to Heat using Kolla as an example.
 
 Only source containers are supported.
 
-.. WARNING::
+.. warning::
 
-   Kolla dev mode is intended for OpenStack hacking/development only. Do not
+   Kolla dev mode is intended for OpenStack hacking or development only.
-   use this in production!
+   Do not use this in production!
 
 Enabling Kolla "dev mode"
 -------------------------
@@ -25,16 +25,22 @@ Enabling Kolla "dev mode"
 To enable dev mode for all supported services, set in
 ``/etc/kolla/globals.yml``:
 
-::
+.. path /etc/kolla/globals.yml
+.. code-block:: none
 
    kolla_dev_mode: true
 
+.. end
+
 To enable it just for heat, set:
 
-::
+.. path /etc/kolla/globals.yml
+.. code-block:: none
 
    heat_dev_mode: true
 
+.. end
+
 Usage
 -----
 
@@ -44,33 +50,41 @@ container's virtualenv under the location expected by the service on startup.
 
 After making code changes, simply restart the container to pick them up:
 
-::
+.. code-block:: console
 
    docker restart heat_api
 
+.. end
+
 Debugging
 ---------
 
 ``remote_pdb`` can be used to perform debugging with Kolla containers. First,
 make sure it is installed in the container in question:
 
-::
+.. code-block:: console
 
    docker exec -it -u root heat_api pip install remote_pdb
 
+.. end
+
 Then, set your breakpoint as follows:
 
-::
+.. code-block:: none
 
    from remote_pdb import RemotePdb
    RemotePdb('127.0.0.1', 4444).set_trace()
 
+.. end
+
 Once you run the code(restart the container), pdb can be accessed using
 ``socat``:
 
-::
+.. code-block:: console
 
    socat readline tcp:127.0.0.1:4444
 
-For more information on remote_pdb, see
+.. end
-https://pypi.python.org/pypi/remote-pdb.
+
+Learn more information about `remote_pdb
+<https://pypi.python.org/pypi/remote-pdb>`_.

doc/source/contributor/running-tests.rst

@@ -6,8 +6,9 @@ Running tests
 
 Kolla-ansible contains a suit of tests in the ``tests`` directory.
 
-Any proposed code change in gerrit is automatically rejected by the OpenStack
+Any proposed code change in gerrit is automatically rejected by the
-Jenkins server [#f1]_ if the change causes test failures.
+`OpenStack Jenkins server <https://docs.openstack.org/infra/system-config/jjb.html>`__
+if the change causes test failures.
 
 It is recommended for developers to run the test suite before submitting patch
 for review. This allows to catch errors as early as possible.
@@ -22,30 +23,36 @@ so the only package you install is ``tox`` itself:
 
 .. code-block:: console
 
-    $ pip install tox
+   pip install tox
 
-See `the unit testing section of the Testing wiki page`_ for more information.
+.. end
-Following are some simple examples.
+
+For more information, see `the unit testing section of the Testing wiki page
+<https://wiki.openstack.org/wiki/Testing#Unit_Tests>`_. For example:
 
 To run the Python 2.7 tests:
 
 .. code-block:: console
 
-    $ tox -e py27
+   tox -e py27
+
+.. end
 
 To run the style tests:
 
 .. code-block:: console
 
-    $ tox -e pep8
+   tox -e pep8
+
+.. end
 
 To run multiple tests separate items by commas:
 
 .. code-block:: console
 
-    $ tox -e py27,py34,pep8
+   tox -e py27,py35,pep8
 
-.. _the unit testing section of the Testing wiki page: https://wiki.openstack.org/wiki/Testing#Unit_Tests
+.. end
 
 Running a subset of tests
 -------------------------
@@ -59,31 +66,39 @@ directory use:
 
 .. code-block:: console
 
-    $ tox -e py27 kolla-ansible.tests
+   tox -e py27 kolla-ansible.tests
+
+.. end
 
 To run the tests of a specific file
-say ``kolla-ansible/tests/test_kolla_docker.py``:
+``kolla-ansible/tests/test_kolla_docker.py``:
 
 .. code-block:: console
 
-    $ tox -e py27 test_kolla_docker
+   tox -e py27 test_kolla_docker
+
+.. end
 
 To run the tests in the ``ModuleArgsTest`` class in
 the ``kolla-ansible/tests/test_kolla_docker.py`` file:
 
 .. code-block:: console
 
-    $ tox -e py27 test_kolla_docker.ModuleArgsTest
+   tox -e py27 test_kolla_docker.ModuleArgsTest
+
+.. end
 
 To run the ``ModuleArgsTest.test_module_args`` test method in
 the ``kolla-ansible/tests/test_kolla_docker.py`` file:
 
 .. code-block:: console
 
-    $ tox -e py27 test_kolla_docker.ModuleArgsTest.test_module_args
+   tox -e py27 test_kolla_docker.ModuleArgsTest.test_module_args
+
+.. end
 
 Debugging unit tests
-------------------------
+--------------------
 
 In order to break into the debugger from a unit test we need to insert
 a breaking point to the code:
@@ -92,15 +107,17 @@ a breaking point to the code:
 
    import pdb; pdb.set_trace()
 
-Then run ``tox`` with the debug environment as one of the following::
+.. end
+
+Then run ``tox`` with the debug environment as one of the following:
+
+.. code-block:: console
 
    tox -e debug
    tox -e debug test_file_name.TestClass.test_name
 
-For more information see the `oslotest documentation
+.. end
+
+For more information, see the `oslotest documentation
 <https://docs.openstack.org/oslotest/latest/user/features.html#debugging-with-oslo-debug-helper>`_.
 
-
-.. rubric:: Footnotes
-
-.. [#f1] See https://docs.openstack.org/infra/system-config/jjb.html

doc/source/contributor/vagrant-dev-env.rst

@@ -42,56 +42,96 @@ choice. Various downloads can be found at the `Vagrant downloads
 
 Install required dependencies as follows:
 
-On CentOS::
+For CentOS 7 or later:
+
+.. code-block:: console
 
    sudo yum install ruby-devel libvirt-devel zlib-devel libpng-devel gcc \
    qemu-kvm qemu-img libvirt libvirt-python libvirt-client virt-install \
    bridge-utils git
 
-On Ubuntu 16.04 or later::
+.. end
 
-  sudo apt-get install vagrant ruby-dev ruby-libvirt python-libvirt libvirt-dev nfs-kernel-server zlib1g-dev libpng12-dev gcc git
+For Ubuntu 16.04 or later:
 
-.. note:: Many distros ship outdated versions of Vagrant by default. When in
+.. code-block:: console
+
+   sudo apt-get install vagrant ruby-dev ruby-libvirt python-libvirt \
+   libvirt-dev nfs-kernel-server zlib1g-dev libpng12-dev gcc git
+
+.. end
+
+.. note::
+
+   Many distros ship outdated versions of Vagrant by default. When in
    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)::
+(inside each vm):
+
+.. code-block:: console
 
    vagrant plugin install vagrant-hostmanager
 
-If you are going to use VirtualBox, then install vagrant-vbguest::
+.. end
+
+If you are going to use VirtualBox, then install vagrant-vbguest:
+
+.. code-block:: console
 
    vagrant plugin install vagrant-vbguest
 
+.. end
+
 Vagrant supports a wide range of virtualization technologies. If VirtualBox is
 used, the vbguest plugin will be required to install the VirtualBox Guest
-Additions in the virtual machine::
+Additions in the virtual machine:
+
+.. code-block:: console
 
    vagrant plugin install vagrant-vbguest
 
+.. end
+
 This documentation focuses on libvirt specifics. To install vagrant-libvirt
-plugin::
+plugin:
+
+.. code-block:: console
 
    vagrant plugin install --plugin-version ">= 0.0.31" vagrant-libvirt
 
+.. end
+
 Some Linux distributions offer vagrant-libvirt packages, but the version they
 provide tends to be too old to run Kolla. A version of >= 0.0.31 is required.
 
 To use libvirt from Vagrant with a low privileges user without being asked for
-a password, add the user to the libvirt group::
+a password, add the user to the libvirt group:
+
+.. code-block:: console
 
    sudo gpasswd -a ${USER} libvirt
    newgrp libvirt
 
+.. end
+
 Setup NFS to permit file sharing between host and VMs. Contrary to the rsync
 method, NFS allows both way synchronization and offers much better performance
-than VirtualBox shared folders. On CentOS::
+than VirtualBox shared folders. For CentOS:
+
+#. Add the virtual interfaces to the internal zone:
+
+.. code-block:: console
 
-    # Add the virtual interfaces to the internal zone
    sudo firewall-cmd --zone=internal --add-interface=virbr0
    sudo firewall-cmd --zone=internal --add-interface=virbr1
-    # Enable nfs, rpc-bind and mountd services for firewalld
+
+.. end
+
+#. Enable nfs, rpc-bind and mountd services for firewalld:
+
+.. code-block:: console
+
    sudo firewall-cmd --permanent --zone=internal --add-service=nfs
    sudo firewall-cmd --permanent --zone=internal --add-service=rpc-bind
    sudo firewall-cmd --permanent --zone=internal --add-service=mountd
@@ -100,30 +140,50 @@ than VirtualBox shared folders. On CentOS::
    sudo firewall-cmd --permanent --add-port=111/udp
    sudo firewall-cmd --permanent --add-port=111/tcp
    sudo firewall-cmd --reload
-    # Start required services for NFS
+
+.. end
+
+#. Start required services for NFS:
+
+.. code-block:: console
+
    sudo systemctl restart firewalld
    sudo systemctl start nfs-server
    sudo systemctl start rpcbind.service
 
+.. end
+
 Ensure your system has libvirt and associated software installed and setup
-correctly. On CentOS::
+correctly. For CentOS:
+
+.. code-block:: console
 
    sudo systemctl start libvirtd
    sudo systemctl enable libvirtd
 
-Find a location in the system's home directory and checkout Kolla repos::
+.. end
+
+Find a location in the system's home directory and checkout Kolla repos:
+
+.. code-block:: console
 
    git clone https://git.openstack.org/openstack/kolla-ansible
    git clone https://git.openstack.org/openstack/kolla
 
+.. end
+
 Both repos must share the same parent directory so the bootstrap code can
 locate them.
 
 Developers can now tweak the Vagrantfile or bring up the default **all-in-one**
-CentOS 7-based environment::
+CentOS 7-based environment:
+
+.. code-block:: console
 
    cd kolla-ansible/contrib/dev/vagrant && vagrant up
 
+.. end
+
 The command ``vagrant status`` provides a quick overview of the VMs composing
 the environment.
 
@@ -131,10 +191,14 @@ Vagrant Up
 ==========
 
 Once Vagrant has completed deploying all nodes, the next step is to launch
-Kolla. First, connect with the **operator** node::
+Kolla. First, connect with the **operator** node:
+
+.. code-block:: console
 
    vagrant ssh operator
 
+.. end
+
 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 use
 it as a mirror. Ansible may use this registry to pull images from.
@@ -150,42 +214,63 @@ like ``vagrant destroy``.
 Building images
 ---------------
 
-Once logged on the **operator** VM call the ``kolla-build`` utility::
+Once logged on the **operator** VM call the ``kolla-build`` utility:
+
+.. code-block:: console
 
    kolla-build
 
-``kolla-build`` accept arguments as documented in `Building Container Images`_.
+.. end
+
+``kolla-build`` accept arguments as documented in `Building Container Images
+<https://docs.openstack.org/kolla/latest/admin/image-building.html>`_.
 It builds Docker images and pushes them to the local registry if the **push**
 option is enabled (in Vagrant this is the default behaviour).
 
 Deploying OpenStack with Kolla
 ------------------------------
 
-Deploy **all-in-one** with::
+To deploy **all-in-one**:
+
+.. code-block:: console
 
    sudo kolla-ansible deploy
 
-Deploy multinode
+.. end
-On Centos 7::
+
+To deploy multinode:
+
+For Centos 7:
+
+.. code-block:: console
 
    sudo kolla-ansible deploy -i /usr/share/kolla-ansible/ansible/inventory/multinode
 
-On Ubuntu 16.04 or later::
+.. end
+
+For Ubuntu 16.04 or later:
+
+.. code-block:: console
 
    sudo kolla-ansible deploy -i /usr/local/share/kolla-ansible/ansible/inventory/multinode
 
-Validate OpenStack is operational::
+.. end
+
+Validate OpenStack is operational:
+
+.. code-block:: console
 
    kolla-ansible post-deploy
    . /etc/kolla/admin-openrc.sh
    openstack user list
 
-Or navigate to http://172.28.128.254/ with a web browser.
+.. end
+
+Or navigate to ``http://172.28.128.254/`` with a web browser.
 
 Further Reading
 ===============
 
 All Vagrant documentation can be found at
-`Vagrant documentation` <https://www.vagrantup.com/docs/>`__.
+`Vagrant documentation <https://www.vagrantup.com/docs/>`_.
 
-.. _Building Container Images: https://docs.openstack.org/kolla/latest/admin/image-building.html