diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index a9d6a7d..88b16aa 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -14,4 +14,4 @@ Pull requests submitted through GitHub will be ignored.
 
 Bugs should be filed on Launchpad, not GitHub:
 
-   https://bugs.launchpad.net/oslo.serialization
\ No newline at end of file
+   https://bugs.launchpad.net/oslo
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
index 8cb3146..2ca75d1 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributing.rst
@@ -1 +1,5 @@
-.. include:: ../../CONTRIBUTING.rst
\ No newline at end of file
+==============
+ Contributing
+==============
+
+.. include:: ../../CONTRIBUTING.rst
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
index 6b2b3ec..a6210d3 100644
--- a/doc/source/readme.rst
+++ b/doc/source/readme.rst
@@ -1 +1 @@
-.. include:: ../README.rst
\ No newline at end of file
+.. include:: ../../README.rst
diff --git a/setup.cfg b/setup.cfg
index 7c2b0f0..03a0918 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -26,6 +26,9 @@ packages =
 namespace_packages =
     oslo
 
+[pbr]
+warnerrors = true
+
 [build_sphinx]
 source-dir = doc/source
 build-dir = doc/build
@@ -46,4 +49,4 @@ input_file = oslo.serialization/locale/oslo.serialization.pot
 [extract_messages]
 keywords = _ gettext ngettext l_ lazy_gettext
 mapping_file = babel.cfg
-output_file = oslo.serialization/locale/oslo.serialization.pot
\ No newline at end of file
+output_file = oslo.serialization/locale/oslo.serialization.pot
diff --git a/test-requirements.txt b/test-requirements.txt
index 7f0ac98..a3504ed 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -1,7 +1,11 @@
 hacking>=0.5.6,<0.8
 mock>=1.0
 netaddr
+
+# this is required for the docs build jobs
+sphinx>=1.1.2,!=1.2.0,<1.3
 oslosphinx
+
 oslotest
 simplejson
 oslo.i18n>=0.2.0
diff --git a/tox.ini b/tox.ini
index 95d4e1f..c5bd950 100644
--- a/tox.ini
+++ b/tox.ini
@@ -22,6 +22,9 @@ commands = flake8
 [testenv:venv]
 commands = {posargs}
 
+[testenv:docs]
+commands = python setup.py build_sphinx
+
 [testenv:cover]
 commands = python setup.py testr --coverage --testr-args='{posargs}'
 
@@ -32,4 +35,4 @@ commands = python setup.py testr --coverage --testr-args='{posargs}'
 show-source = True
 ignore = E123,E125,H803
 builtins = _
-exclude=.venv,.git,.tox,dist,doc,*openstack/common*,*lib/python*,*egg,build
\ No newline at end of file
+exclude=.venv,.git,.tox,dist,doc,*openstack/common*,*lib/python*,*egg,build