diff --git a/doc/image-building.rst b/doc/image-building.rst
index cd6962b284..074acc9022 100644
--- a/doc/image-building.rst
+++ b/doc/image-building.rst
@@ -96,8 +96,9 @@ repository named ``mykollarepo``::
 
     kolla-build -n mykollarepo --push
 
-To push images to a :ref:`local registry<deploy_a_registry>`, use
-``--registry`` flag::
+To push images to a `local registry
+<https://docs.openstack.org/kolla-ansible/latest/multinode.html#deploy-a-registry>`_,
+use ``--registry`` flag::
 
     kolla-build --registry 172.22.2.81:5000 --push
 
@@ -415,7 +416,8 @@ To make kolla-ansible pull images from a local registry, set
 ``"docker_registry"`` to ``"172.22.2.81:5000"`` in
 ``"/etc/kolla/globals.yml"``. Make sure Docker is allowed to pull images from
 insecure registry. See
-:ref:`Docker Insecure Registry Config <deploy_a_registry>`.
+`Docker Insecure Registry
+<https://docs.openstack.org/kolla-ansible/latest/multinode.html#deploy-a-registry>`_.
 
 Building behind a proxy
 -----------------------
diff --git a/setup.cfg b/setup.cfg
index 4eefef9691..b1825339e0 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -47,6 +47,7 @@ setup-hooks =
 all_files = 1
 build-dir = doc/build
 source-dir = doc
+warning-is-error = 1
 
 [build_releasenotes]
 all_files = 1
diff --git a/tox.ini b/tox.ini
index 05af3d118a..a3e0df0ff9 100644
--- a/tox.ini
+++ b/tox.ini
@@ -46,6 +46,7 @@ commands = {posargs}
 
 [testenv:docs]
 commands =
+  rm -rf doc/build
   doc8 doc
   python setup.py build_sphinx