diff --git a/README.rst b/README.rst
index 1854183..661a54c 100644
--- a/README.rst
+++ b/README.rst
@@ -1,6 +1,6 @@
-========================
+===============
 RefStack Client
-========================
+===============
 
 RefStack-client team and repository tags
 ########################################
diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 0000000..0bb0c37
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,2 @@
+sphinx>=1.6.2  # BSD
+openstackdocstheme>=1.11.0  # Apache-2.0
diff --git a/specs/README.rst b/specs/README.rst
index a3460f9..eee8a20 100644
--- a/specs/README.rst
+++ b/specs/README.rst
@@ -1,6 +1,6 @@
-=======================
+==============================
 Refstack-Client Specifications
-=======================
+==============================
 
 This folder is used to hold design specifications for additions
 to the refstack-client project. Reviews of the specs are done in gerrit, using a
diff --git a/specs/newton/approved/refstack-waiver.rst b/specs/newton/approved/refstack-waiver.rst
index 015fab7..47f3c7c 100644
--- a/specs/newton/approved/refstack-waiver.rst
+++ b/specs/newton/approved/refstack-waiver.rst
@@ -132,6 +132,7 @@ installation.
 Use tests_list as withelist for ostestr in order to re-run failed test cases.
 
 .. code-block:: bash
+
    ostestr --serial -w test_list
 
 Input: test_list and conf-file files.
diff --git a/specs/queens/approved/tempest_autoconfig.rst b/specs/queens/approved/tempest_autoconfig.rst
index b68aa11..2b24774 100644
--- a/specs/queens/approved/tempest_autoconfig.rst
+++ b/specs/queens/approved/tempest_autoconfig.rst
@@ -17,11 +17,12 @@ about tempest, the tempest.conf can be created automatically by the
 refstack-client and provide an example tempest.conf populated with values from
 the target cloud.
 
-::
+.. code-block:: bash
+
     $ source openstackrc file
     $ refstack-client config -h
-        --os-cloud <name of the cloud> # Using specific cloud.yaml files
-        --use-test-accounts <Use accounts from accounts.yaml>
+          --os-cloud <name of the cloud> # Using specific cloud.yaml files
+          --use-test-accounts <Use accounts from accounts.yaml>
     $ # we can also use discover-tempest-config to generate tempest.conf
     $ discover-tempest-config --create
 
diff --git a/test-requirements.txt b/test-requirements.txt
index 92c5310..8f630cf 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -2,11 +2,8 @@ pep8==1.4.5
 pyflakes>=0.7.2,<0.7.4
 flake8==2.0
 docutils>=0.11  # OSI-Approved Open Source, Public Domain
-# required to build documentation
-sphinx>=1.6.2  # BSD
 stestr>=1.1.0 # Apache-2.0
 testtools>=0.9.34
 mock
 coverage
 httmock
-openstackdocstheme>=1.11.0  # Apache-2.0
diff --git a/tox.ini b/tox.ini
index d84b865..fe5371a 100644
--- a/tox.ini
+++ b/tox.ini
@@ -33,7 +33,8 @@ commands =
   coverage report
 
 [testenv:docs]
-commands = python setup.py build_sphinx {posargs}
+deps = -r{toxinidir}/doc/requirements.txt
+commands = sphinx-build -b html doc/source doc/build/html
 
 [flake8]
 # E125 continuation line does not distinguish itself from next logical line