Follow the new PTI for document build

For compliance with the Project Testing Interface as described in:
[1] https://governance.openstack.org/tc/reference/project-testing-interface.html
[2] http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html

Change-Id: I302aced3b50b038900375e9632ca7ed136f32914

doc/requirements.txt

@@ -0,0 +1,7 @@
+# The order of packages is significant, because pip processes them in the order
+# of appearance. Changing the order has an impact on the overall integration
+# process, which may cause wedges in the gate later.
+doc8>=0.6.0 # Apache-2.0
+openstackdocstheme>=1.18.1 # Apache-2.0
+reno>=2.5.0 # Apache-2.0
+sphinx!=1.6.6,>=1.6.2 # BSD

doc/source/admin/image-building.rst

@@ -271,7 +271,7 @@ within the Horizon Dockerfile.
 First, create a file to contain the customisations, for example:
 ``template-overrides.j2``. In this place the following:
 
-.. code-block:: none
+.. code-block:: console
 
    {% extends parent_template %}
 
@@ -320,10 +320,10 @@ as part of a binary install type build:
 * ``mod_ssl``
 * ``gettext``
 
-To add a package to this list, say, ``iproute``, first create a file, for example,
+To add a package to this list, say, ``iproute``, first create a file,
-``template-overrides.j2``. In this place the following:
+for example, ``template-overrides.j2``. In this place the following:
 
-.. code-block:: none
+.. code-block:: console
 
    {% extends parent_template %}
 
@@ -389,7 +389,7 @@ modifications to every Dockerfile.
 For example, to add the ``networking-cisco`` plugin to the ``neutron_server``
 image, one may want to add the following to the ``template-override`` file:
 
-.. code-block:: none
+.. code-block:: console
 
    {% extends parent_template %}
 
@@ -451,7 +451,7 @@ structure:
 
 The template now becomes:
 
-.. code-block:: none
+.. code-block:: console
 
    {% block neutron_server_footer %}
    ADD plugins-archive /
@@ -524,7 +524,7 @@ feature for binary build type.
 
 The template now becomes:
 
-.. code-block:: none
+.. code-block:: console
 
    {% block neutron_server_footer %}
    ADD additions-archive /

doc/source/admin/template-override/ovs-dpdk.rst

@@ -17,7 +17,7 @@ ________________
 
 In this place the ``contrib/template-override/ovs-dpdk.j2`` file:
 
-.. code-block:: none
+.. code-block:: console
 
    [openvswitch-base-plugin-ovs]
    type = git

doc/source/contributor/CONTRIBUTING.rst

@@ -55,8 +55,8 @@ should inherit from the provided ``openstack-base`` image, while supporting and
 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, for example, ``horizon``. Services that consist of multiple
+same as that service, for example, ``horizon``. Services that consist of
-processes generally use a base image and child images, for example,
+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
@@ -67,7 +67,7 @@ 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:
 
-.. code-block: none
+.. code-block:: console
 
    FROM {{ namespace }}/{{ image_prefix }}openstack-base:{{ tag }}
    LABEL maintainer="{{ maintainer }}" name="{{ image_name }}" build-date="{{ build_date }}"

test-requirements.txt

@@ -6,14 +6,11 @@ bashate>=0.5.1 # Apache-2.0
 beautifulsoup4>=4.6.0 # MIT
 coverage!=4.4,>=4.0 # Apache-2.0
 ddt>=1.0.1 # MIT
-doc8>=0.6.0 # Apache-2.0
 extras>=1.0.0 # MIT
 graphviz!=0.5.0,>=0.4 # MIT License
 hacking!=0.13.0,<0.14,>=0.12.0 # Apache-2.0
-openstackdocstheme>=1.18.1 # Apache-2.0
 oslo.log>=3.36.0 # Apache-2.0
 oslotest>=3.2.0 # Apache-2.0
-reno>=2.5.0 # Apache-2.0
 PrettyTable<0.8,>=0.7.1 # BSD
 PyYAML>=3.10 # MIT
 python-barbicanclient!=4.5.0,!=4.5.1,>=4.0.0 # Apache-2.0
@@ -22,7 +19,6 @@ python-neutronclient>=6.3.0 # Apache-2.0
 python-openstackclient>=3.12.0 # Apache-2.0
 python-swiftclient>=3.2.0 # Apache-2.0
 pytz>=2013.6 # MIT
-sphinx!=1.6.6,>=1.6.2 # BSD
 testrepository>=0.0.18 # Apache-2.0/BSD
 testscenarios>=0.4 # Apache-2.0/BSD
 testtools>=2.2.0 # MIT

tox.ini

@@ -49,10 +49,11 @@ commands = bandit -r docker kolla tests tools
 commands = {posargs}
 
 [testenv:docs]
+deps = -r{toxinidir}/doc/requirements.txt
 commands =
   rm -rf doc/build
   doc8 doc
-  python setup.py build_sphinx
+  sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:setupenv]
 commands =
@@ -236,6 +237,7 @@ commands=
   oslo-config-generator --config-file etc/oslo-config-generator/kolla-build.conf
 
 [testenv:releasenotes]
+deps = -r{toxinidir}/doc/requirements.txt
 commands =
   rm -rf releasenotes/build
   sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html