diff --git a/doc/source/conf.py b/doc/source/conf.py
index 70de5af..a5ac75d 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -42,7 +42,7 @@ except ImportError:
     pass
 
 # Feed configuration for yasfb
-feed_base_url = 'http://specs.openstack.org/openstack/trove-specs'
+feed_base_url = 'https://specs.openstack.org/openstack/trove-specs'
 feed_author = 'OpenStack Development Team'
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
diff --git a/requirements.txt b/requirements.txt
index 2131709..21d9830 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,5 +1,5 @@
-openstackdocstheme>=1.11.0
-sphinx!=1.6.6,!=1.6.7;python_version>='3.4'  # BSD
+openstackdocstheme>=2.0.0
+sphinx>=2.0.0,!=2.1.0  # BSD
 testrepository>=0.0.18
 testtools>=0.9.34
 yasfb>=0.5.1
diff --git a/setup.cfg b/setup.cfg
index 8118f09..ff8c2f0 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -11,14 +11,3 @@ classifier =
     Intended Audience :: Developers
     License :: OSI Approved :: Apache Software License
     Operating System :: POSIX :: Linux
-
-[build_sphinx]
-source-dir = doc/source
-build-dir = doc/build
-all_files = 1
-
-[pbr]
-warnerrors = True
-
-[upload_sphinx]
-upload-dir = doc/build/html
diff --git a/specs/liberty/cassandra-configuration-groups.rst b/specs/liberty/cassandra-configuration-groups.rst
index 7ac1547..ce8b364 100644
--- a/specs/liberty/cassandra-configuration-groups.rst
+++ b/specs/liberty/cassandra-configuration-groups.rst
@@ -255,5 +255,5 @@ The datastore documentation should be updated to reflect the enabled features.
 References
 ==========
 
-.. [1] Documentation on Cassandra 2.1: http://docs.datastax.com/en/cassandra/2.1/cassandra/gettingStartedCassandraIntro.html
-.. [2] Documentation on Cassandra 2.1 configuration properties: http://docs.datastax.com/en/cassandra/2.1/cassandra/configuration/configTOC.html
+Documentation on Cassandra 2.1: http://docs.datastax.com/en/cassandra/2.1/cassandra/gettingStartedCassandraIntro.html
+Documentation on Cassandra 2.1 configuration properties: http://docs.datastax.com/en/cassandra/2.1/cassandra/configuration/configTOC.html
diff --git a/specs/liberty/cassandra-database-user-functions.rst b/specs/liberty/cassandra-database-user-functions.rst
index 6a3de96..da41512 100644
--- a/specs/liberty/cassandra-database-user-functions.rst
+++ b/specs/liberty/cassandra-database-user-functions.rst
@@ -29,7 +29,7 @@ Proposed Change
 ===============
 
 The patch set will implement the following keyspace and user related
-functionality for Cassandra 2.1 datastore:
+functionality for Cassandra 2.1 [2]_ datastore:
 
 User Functions:
 
@@ -116,7 +116,8 @@ None
 Guest Agent
 -----------
 
-The current implementation uses the CQLSH command line client to interface with
+The current implementation uses the CQLSH [3]_ command line client to
+interface with
 the underlying database. Trove talks to the CQLSH client via the available
 shell and relies on parsing the output of the client to determine the current
 state of the datastore and status of the last operation.
diff --git a/specs/liberty/percona-cluster.rst b/specs/liberty/percona-cluster.rst
index 613e402..c35d74b 100644
--- a/specs/liberty/percona-cluster.rst
+++ b/specs/liberty/percona-cluster.rst
@@ -680,6 +680,9 @@ List of other cluster related blueprints. These blueprints will likely cause
 conflicts with changes.
 
 .. [1] bp/cluster-scaling: https://blueprints.launchpad.net/trove/+spec/cluster-scaling
-.. [2] bp/mysql-manager-refactor: https://blueprints.launchpad.net/trove/+spec/mysql-manager-refactor
-.. [3] bp/cluster-user-management: https://blueprints.launchpad.net/trove/+spec/cluster-user-management
 .. [4] percona-xtradb-with-replica: https://blueprints.launchpad.net/trove/+spec/percona-add-replica-of-cluster
+
+bp/mysql-manager-refactor:
+    https://blueprints.launchpad.net/trove/+spec/mysql-manager-refactor
+bp/cluster-user-management:
+    https://blueprints.launchpad.net/trove/+spec/cluster-user-management
diff --git a/specs/mitaka/mariadb-gtid-replication.rst b/specs/mitaka/mariadb-gtid-replication.rst
index 15d98bd..d3ba382 100644
--- a/specs/mitaka/mariadb-gtid-replication.rst
+++ b/specs/mitaka/mariadb-gtid-replication.rst
@@ -59,7 +59,7 @@ in order to support replication for MariaDB.
 The SQL issued to set a new empty slave server and replicate all of the
 master's binlog from the start is as follows [2]_:
 
-.. code-block:: sql
+.. code-block:: none
 
     CHANGE MASTER TO master_host="%(host)s", master_port=%(port)s, \
     master_user="%(user)s", master_password="%(password)s", \
diff --git a/specs/mitaka/pgsql-replication.rst b/specs/mitaka/pgsql-replication.rst
index 98f4540..c2c2ee4 100644
--- a/specs/mitaka/pgsql-replication.rst
+++ b/specs/mitaka/pgsql-replication.rst
@@ -279,7 +279,8 @@ None.
 Dependencies
 ============
 
-pg_basebackup incremental backup and restore strategy for PostgreSQL. [10]_
+pg_basebackup incremental backup and restore strategy for PostgreSQL.
+[3]_ [10]_
 
 Testing
 =======
@@ -310,11 +311,11 @@ References
 
 .. [4] http://www.postgresql.org/docs/9.0/static/wal-configuration.html
 
-.. [5] http://www.postgresql.org/docs/9.4/static/warm-standby-failover.html
+[5] http://www.postgresql.org/docs/9.4/static/warm-standby-failover.html
 
 .. [6] http://www.postgresql.org/docs/current/static/sql-createrole.html
 
-.. [7] http://www.postgresql.org/message-id/flat/CA+TgmobWQJ-GCa_tWUc4=80A
+[7] http://www.postgresql.org/message-id/flat/CA+TgmobWQJ-GCa_tWUc4=80A
        1RJ2_+Rq3w_MqaVguk_q018dqw@mail.gmail.com#CA+TgmobWQJ-GCa_tWUc4=80A1RJ
        2_+Rq3w_MqaVguk_q018dqw@mail.gmail.com
 
diff --git a/specs/mitaka/pxc-grow-shrink-cluster.rst b/specs/mitaka/pxc-grow-shrink-cluster.rst
index 4707f0d..cf1c2c8 100644
--- a/specs/mitaka/pxc-grow-shrink-cluster.rst
+++ b/specs/mitaka/pxc-grow-shrink-cluster.rst
@@ -266,7 +266,7 @@ References
 
 .. [1] https://www.percona.com/doc/percona-xtradb-cluster/5.5/howtos/ubuntu_howto.html
 
-.. [2] https://www.percona.com/doc/percona-xtradb-cluster/5.5/manual/bootstrap.html#bootstrap
+https://www.percona.com/doc/percona-xtradb-cluster/5.5/manual/bootstrap.html#bootstrap
 
 Appendix
 ========
diff --git a/specs/mitaka/remove-sql-schema-downgrades.rst b/specs/mitaka/remove-sql-schema-downgrades.rst
index 5a95ea4..7f2e446 100644
--- a/specs/mitaka/remove-sql-schema-downgrades.rst
+++ b/specs/mitaka/remove-sql-schema-downgrades.rst
@@ -151,11 +151,11 @@ None
 References
 ==========
 
-.. [1] https://review.openstack.org/#/c/152337/
-.. [2] https://review.openstack.org/#/c/167554/2
-.. [3] https://review.openstack.org/#/c/167834/
-.. [4] https://review.openstack.org/#/c/167189/2
-.. [5] https://review.openstack.org/#/c/165740/
+* https://review.openstack.org/#/c/152337/
+* https://review.openstack.org/#/c/167554/2
+* https://review.openstack.org/#/c/167834/
+* https://review.openstack.org/#/c/167189/2
+* https://review.openstack.org/#/c/165740/
 
 
 Appendix
diff --git a/specs/mitaka/volume-type-on-create.rst b/specs/mitaka/volume-type-on-create.rst
index 31fc83b..dc6da6f 100644
--- a/specs/mitaka/volume-type-on-create.rst
+++ b/specs/mitaka/volume-type-on-create.rst
@@ -78,13 +78,13 @@ structure accepted by the instance and cluster create API calls.
 
 API payload defining a volume of size '1' and Cinder volume type 'my-type-1':
 
-.. code-block:: json
+.. code-block:: none
 
     'volume': {'size': '1', 'type': 'my-type-1'}
 
 API payload defining a volume of size '1' and no Cinder volume type:
 
-.. code-block:: json
+.. code-block:: none
 
     'volume': {'size': '1', 'type': None}
     'volume': {'size': '1'}
diff --git a/specs/newton/couchdb-configuration-groups.rst b/specs/newton/couchdb-configuration-groups.rst
index 3faba7b..40e4814 100644
--- a/specs/newton/couchdb-configuration-groups.rst
+++ b/specs/newton/couchdb-configuration-groups.rst
@@ -153,7 +153,7 @@ The datastore documentation should be updated to reflect the enabled features.
 References
 ==========
 
-.. [1] Documentation on CouchDB configuration: http://docs.couchdb.org/en/stable/config/index.html
+* Documentation on CouchDB configuration: http://docs.couchdb.org/en/stable/config/index.html
 
 Appendix
 ========
diff --git a/specs/newton/datastore-version-volume-type-support.rst b/specs/newton/datastore-version-volume-type-support.rst
index f522f64..59cb8b2 100644
--- a/specs/newton/datastore-version-volume-type-support.rst
+++ b/specs/newton/datastore-version-volume-type-support.rst
@@ -32,7 +32,7 @@ datastore-version in the same way that they can limit Nova flavors.
 Proposed Change
 ===============
 
-The implentation that associated flavors with datastores [1][2]
+The implentation that associated flavors with datastores [1]_ [2]_
 created a generic framework that provided for the specification of
 datastore-version-metadata. This metadata was stored into a table in
 the database called datastore_version_metadata.
diff --git a/specs/newton/db2-config-groups.rst b/specs/newton/db2-config-groups.rst
index 0b9f8eb..487cbf5 100644
--- a/specs/newton/db2-config-groups.rst
+++ b/specs/newton/db2-config-groups.rst
@@ -182,9 +182,9 @@ Appendix
 ========
 
 The database manager configuration parameters have been listed below. For a
-detailed description of each parameter, please refer[1]. The parameters listed
+detailed description of each parameter, please refer[1]_. The parameters listed
 below are the ones that are relevant for the DB2 Express-C version. The link
-referenced in [1] gives a complete list of parameters for the DB2 enterprise
+referenced in [1]_ gives a complete list of parameters for the DB2 enterprise
 edition::
 
     AGENTPRI
diff --git a/specs/newton/db2-online-backup.rst b/specs/newton/db2-online-backup.rst
index 03cf8dd..5f66ab6 100644
--- a/specs/newton/db2-online-backup.rst
+++ b/specs/newton/db2-online-backup.rst
@@ -70,8 +70,8 @@ they are archived. Archive logging allows users to restore databases by roll
 forwarding to a particular point in time or a point before failure. Hence,
 users can restore a database from a backup image and roll forward to a
 particular point using logs thus getting it to a consistent state. For an
-introduction to archive logging, please refer [1] and for an overview of how
-transactional logging works in DB2, please refer [2].
+introduction to archive logging, please refer [1]_ and for an overview of how
+transactional logging works in DB2, please refer [2]_.
 
 To enable full online backup for Trove, the following steps need to be taken:
 
@@ -132,7 +132,7 @@ in a consistent state.
 
     This command will roll forward the restored database to a consistent state
     by applying the archive logs. To see more details on the ROLLFORWARD
-    command, please refer [3].
+    command, please refer [3]_.
 
 Configuration
 -------------
@@ -264,4 +264,4 @@ References
 Appendix
 ========
 
-None
\ No newline at end of file
+None
diff --git a/specs/ocata/couchbase-cluster.rst b/specs/ocata/couchbase-cluster.rst
index ba509bd..348813f 100644
--- a/specs/ocata/couchbase-cluster.rst
+++ b/specs/ocata/couchbase-cluster.rst
@@ -297,11 +297,11 @@ clustering support.
 References
 ==========
 
-.. [1] Couchbase cluster management: http://docs.couchbase.com/admin/admin/Tasks/cluster-management.html
+* Couchbase cluster management: http://docs.couchbase.com/admin/admin/Tasks/cluster-management.html
 
-.. [2] Couchbase CLI reference: http://developer.couchbase.com/documentation/server/4.0/cli/cli-intro.html
+* Couchbase CLI reference: http://developer.couchbase.com/documentation/server/4.0/cli/cli-intro.html
 
-.. [3] Couchbase cluster API: http://docs.couchbase.com/admin/admin/REST/rest-cluster-intro.html
+* Couchbase cluster API: http://docs.couchbase.com/admin/admin/REST/rest-cluster-intro.html
 
 
 Appendix
diff --git a/specs/ocata/extended-filesystems.rst b/specs/ocata/extended-filesystems.rst
index 2eab03c..9eddf6c 100644
--- a/specs/ocata/extended-filesystems.rst
+++ b/specs/ocata/extended-filesystems.rst
@@ -525,7 +525,7 @@ and mount_point parameters with a new *device_config* list.  The
 *device_config* will supply information about the number and types of
 volumes to be configured on the guest:
 
-.. code-block:: json
+.. code-block:: none
 
     [
         {
diff --git a/tox.ini b/tox.ini
index f8b9999..16c8c1d 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,12 +1,13 @@
 [tox]
-minversion = 1.6
+minversion = 3.1.1
 envlist = docs,py3
 skipsdist = True
+ignore_basepython_conflict = True
+
 
 [testenv]
 basepython = python3
 usedevelop = True
-install_command = pip install -U {opts} {packages}
 setenv = VIRTUAL_ENV={envdir}
 deps = -r{toxinidir}/requirements.txt
 commands = python setup.py testr --slowest --testr-args='{posargs}'
@@ -15,7 +16,7 @@ commands = python setup.py testr --slowest --testr-args='{posargs}'
 commands = {posargs}
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+commands = sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:spelling]
 deps =