Merge "Upgrade the rst convention of the Contributor Guide"6.0.0.0b2

2 files changed, 81 insertions, 58 deletions

diff --git a/doc/source/contributor/CONTRIBUTING.rst b/doc/source/contributor/CONTRIBUTING.rst
index 7b6ce18f4..d50c34462 100644
--- a/doc/source/contributor/CONTRIBUTING.rst
+++ b/doc/source/contributor/CONTRIBUTING.rst
@@ -7,31 +7,30 @@ How To Contribute
 Basics
 ======
 
-#. Our source code is hosted on `OpenStack Kolla Git`_. Bugs should be filed on
-   launchpad_.
+#. Our source code is hosted on `OpenStack Kolla Git
+   <https://git.openstack.org/cgit/openstack/kolla/>`_. Bugs should be filed on
+   `launchpad <https://bugs.launchpad.net/kolla>`_.
 
-#. 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.
 
 #. 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 <https://blueprints.launchpad.net/kolla>`__
+   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_. For simple changes, contributors may optionally
-   add the text "TrivialFix" to the commit message footer to indicate to
-   reviewers a bug is not required.
+   the `commit message <https://wiki.openstack.org/wiki/GitCommitMessages>`_.
+   For simple changes, contributors may optionally add the text "TrivialFix" to
+   the commit message footer to indicate to reviewers a bug is not required.
 
-.. _OpenStack Kolla Git: https://git.openstack.org/cgit/openstack/kolla/
-.. _launchpad: https://bugs.launchpad.net/kolla
-.. _here: https://wiki.openstack.org/wiki/GitCommitMessages
-
-Please use the existing sandbox repository, available at
-https://git.openstack.org/cgit/openstack-dev/sandbox, for learning, understanding
-and testing the `Gerrit Workflow`_.
-
-.. _Gerrit Workflow: https://docs.openstack.org/infra/manual/developers.html#development-workflow
+Please use the existing sandbox repository, available at `sandbox
+<https://git.openstack.org/cgit/openstack-dev/sandbox>`_,
+for learning, understanding and testing the `Gerrit Workflow
+<https://docs.openstack.org/infra/manual/developers.html#development-workflow>`_.
 
 Adding a new service
 ====================
@@ -42,8 +41,9 @@ guidelines aim to help make adding a new service to Kolla a smooth experience.
 
 The image
 ---------
-Kolla follows Docker best practices
-(https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/)
+
+Kolla follows `Best practices for writing Dockerfiles
+<https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/>`__
 when designing and implementing services where at all possible.
 
 We use ``jinja2`` templating syntax to help manage the volume and complexity
@@ -52,37 +52,40 @@ operating systems.
 
 Images should be created under the ``docker`` directory. OpenStack services
 should inherit from the provided ``openstack-base`` image, while supporting and
-infrastructure services (e.g. mongodb) should inherit from ``base``.
+infrastructure services (for example, mongodb) should inherit from ``base``.
 
 Services consisting of only one service should be placed in an image named the
-same as that service, e.g. ``horizon``. Services that consist of multiple
-processes generally use a base image and child images, e.g. ``glance-base``,
-``glance-api``, and ``glance-registry``.
+same as that service, for example, ``horizon``. Services that consist of multiple
+processes generally use a base image and child images, for example,
+``glance-base``, ``glance-api``, and ``glance-registry``.
 
 Jinja2 'blocks' are employed throughout the Dockerfile's to help operators
-customise various stages of the build (refer to
-https://docs.openstack.org/kolla/latest/image-building.html#dockerfile-customisation)
+customise various stages of the build (refer to `Dockerfile Customisation
+<https://docs.openstack.org/kolla/latest/admin/image-building.html#dockerfile-customisation>`__)
 
 Some of these blocks are free form however, there are a subset that should be
 common to every Dockerfile. The overall structure for a multi container service
-is as follows::
+is as follows:
+
+.. code-block: none
+
+   FROM {{ namespace }}/{{ image_prefix }}openstack-base:{{ tag }}
+   LABEL maintainer="{{ maintainer }}" name="{{ image_name }}" build-date="{{ build_date }}"
 
-    FROM {{ namespace }}/{{ image_prefix }}openstack-base:{{ tag }}
-    LABEL maintainer="{{ maintainer }}" name="{{ image_name }}" build-date="{{ build_date }}"
+   {% block << service >>_header %}{% endblock %}
 
-    {% block << service >>_header %}{% endblock %}
+   {% import "macros.j2" as macros with context %}
 
-    {% import "macros.j2" as macros with context %}
+   << binary specific steps >>
 
-    << binary specific steps >>
+   << source specific steps >>
 
-    << source specific steps >>
+   << common steps >>
 
-    << common steps >>
+   {% block << service >>_footer %}{% endblock %}
+   {% block footer %}{% endblock %}
 
-    {% block << service >>_footer %}{% endblock %}
-    {% block footer %}{% endblock %}
+.. note::
 
-.. NOTE::
-  The generic footer block ``{% block footer %}{% endblock %}`` should not be
-  included in base images (e.g. glance-base).
+   The generic footer block ``{% block footer %}{% endblock %}`` should not be
+   included in base images (for example, glance-base).
diff --git a/doc/source/contributor/running-tests.rst b/doc/source/contributor/running-tests.rst
index e60671c9f..2a300bb16 100644
--- a/doc/source/contributor/running-tests.rst
+++ b/doc/source/contributor/running-tests.rst
@@ -8,7 +8,8 @@ Kolla contains a suite of tests in the
 ``tests`` and ``kolla/tests`` directories.
 
 Any proposed code change in gerrit is automatically rejected by the OpenStack
-Jenkins server [#f1]_ if the change causes test failures.
+`Jenkins Job Builder <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.
@@ -23,65 +24,78 @@ 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
+
+See the `unit testing <https://wiki.openstack.org/wiki/Testing#Unit_Tests>`__
+section of the Testing wiki page for more information.
 Following are some simple examples.
 
 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,py35,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
 -------------------------
 
 Instead of running all tests, you can specify an individual directory, file,
-class or method that contains test code, i.e. filter full names of tests by a
-string.
+class or method that contains test code, for example, filter full names of
+tests by a string.
 
-To run the tests located only in the ``kolla/tests``
-directory use:
+To run the tests located only in the ``kolla/tests`` directory:
 
 .. code-block:: console
 
-    $ tox -e py27 kolla.tests
+    tox -e py27 kolla.tests
+
+.. end
 
 To run the tests of a specific file say ``kolla/tests/test_set_config.py``:
 
 .. code-block:: console
 
-    $ tox -e py27 test_set_config
+    tox -e py27 test_set_config
+
+.. end
 
 To run the tests in the ``ConfigFileTest`` class in
 the ``kolla/tests/test_set_config.py`` file:
 
 .. code-block:: console
 
-    $ tox -e py27 test_set_config.ConfigFileTest
+    tox -e py27 test_set_config.ConfigFileTest
+
+.. end
 
 To run the ``ConfigFileTest.test_delete_path_not_exists`` test method in
 the ``kolla/tests/test_set_config.py`` file:
 
 .. code-block:: console
 
-    $ tox -e py27 test_set_config.ConfigFileTest.test_delete_path_not_exists
+    tox -e py27 test_set_config.ConfigFileTest.test_delete_path_not_exists
 
+.. end
 
 Coverage Report Generation
 --------------------------
@@ -90,7 +104,9 @@ In order to get coverage report for Kolla, run the below command.
 
 .. code-block:: console
 
-    $ tox -e cover
+    tox -e cover
+
+.. end
 
 Debugging unit tests
 --------------------
@@ -102,15 +118,19 @@ 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 :command:`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
 
-  tox -e debug
-  tox -e debug test_file_name.TestClass.test_name
+.. 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