diff --git a/doc/source/containers_deployment/architecture.rst b/doc/source/containers_deployment/architecture.rst
index 644b3be5..0d849093 100644
--- a/doc/source/containers_deployment/architecture.rst
+++ b/doc/source/containers_deployment/architecture.rst
@@ -116,10 +116,9 @@ script is called from the `post.yaml` file and it takes a `json` file as
 configuration.
 
 The `docker-puppet.py` execution results in a oneshot container being executed
-(usually named `puppet-$service_name) to generate the configuration options or
+(usually named `puppet-$service_name`) to generate the configuration options or
 run other service specific operations. Example: Create Keystone endpoints.
 
-
 Anatomy of a containerized service template
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -243,21 +242,30 @@ containers steps. These steps are executed sequentially:
 
 #. Containers config files generated per hiera settings.
 #. Load Balancer configuration baremetal
-  #. Step 1 baremetal
-  #. Step 1 containers
+
+   #. Step 1 baremetal
+   #. Step 1 containers
+
 #. Core Services (Database/Rabbit/NTP/etc.)
-  #. Step 2 baremetal
-  #. Step 2 containers
+
+   #. Step 2 baremetal
+   #. Step 2 containers
+
 #. Early Openstack Service setup (Ringbuilder, etc.)
-  #. Step 3 baremetal
-  #. Step 3 containers
+
+   #. Step 3 baremetal
+   #. Step 3 containers
+
 #. General OpenStack Services
-  #. Step 4 baremetal
-  #. Step 4 containers
-  #. Keystone containers post initialization (tenant, service, endpoint creation)
+
+   #. Step 4 baremetal
+   #. Step 4 containers
+   #. Keystone containers post initialization (tenant, service, endpoint creation)
+
 #. Service activation (Pacemaker)
-  #. Step 5 baremetal
-  #. Step 5 containers
+
+   #. Step 5 baremetal
+   #. Step 5 containers
 
 
 Service Bootstrap
diff --git a/doc/source/containers_deployment/undercloud.rst b/doc/source/containers_deployment/undercloud.rst
index aaab2f3e..1c377325 100644
--- a/doc/source/containers_deployment/undercloud.rst
+++ b/doc/source/containers_deployment/undercloud.rst
@@ -166,5 +166,5 @@ second one is `heat-all` which executes the templates and installs the services.
 The latter can be run on baremetal or in a container (tripleoclient will run it
 in a container by default).
 
-Checkout the `TripleO Containers Architecture`_ for more detailed info on how
+Checkout the :doc:`architecture` for more detailed info on how
 TripleO builds, creates and runs containers.
diff --git a/doc/source/post_deployment/upgrade.rst b/doc/source/post_deployment/upgrade.rst
index eaf71fd5..3eac43bf 100644
--- a/doc/source/post_deployment/upgrade.rst
+++ b/doc/source/post_deployment/upgrade.rst
@@ -267,7 +267,7 @@ major-upgrade-composable-steps that comes first, as described above.
 .. _manifests: https://github.com/openstack/tripleo-heat-templates/tree/master/puppet/services
 
 Upgrading the Overcloud to Newton and earlier
------------------------
+---------------------------------------------
 
 .. note::
 
diff --git a/setup.cfg b/setup.cfg
index 9d873ec9..89bbdf77 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -22,6 +22,7 @@ classifier =
 all_files = 1
 build-dir = doc/build
 source-dir = doc/source
+warning-is-error = 1
 
 [egg_info]
 tag_build =
@@ -30,6 +31,3 @@ tag_svn_revision = 0
 
 [wheel]
 universal = 1
-
-[pbr]
-warnerrors = False
diff --git a/test-requirements.txt b/test-requirements.txt
index cf4025f2..28573109 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -1,6 +1,6 @@
 # Doc requirements
-sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
-oslosphinx>=2.2.0  # Apache-2.0
+sphinx>=1.5.1  # BSD
+oslosphinx>=4.7.0 # Apache-2.0
 sphinx_rtd_theme==0.1.7
 
 hacking>=0.10.0,<0.11