diff --git a/doc/source/_static/.placeholder b/doc/source/_static/.placeholder
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/doc/source/cacti.rst b/doc/source/cacti.rst
index 4fd45e2502..0ed636218d 100644
--- a/doc/source/cacti.rst
+++ b/doc/source/cacti.rst
@@ -3,9 +3,9 @@
 .. _cacti:
 
 Cacti
-######
+#####
 
-The `Cacti <http://www.cacti.net/>`_ network graphing tool
+The `Cacti network graphing tool <http://www.cacti.net/>`_
 is installed on cacti.openstack.org.
 
 At a Glance
diff --git a/doc/source/elastic-recheck.rst b/doc/source/elastic-recheck.rst
index 2f801f9816..be8810c4a0 100644
--- a/doc/source/elastic-recheck.rst
+++ b/doc/source/elastic-recheck.rst
@@ -3,7 +3,7 @@
 .. _elastic-recheck:
 
 Elastic-Recheck
-######
+###############
 
 
 
diff --git a/doc/source/gerrit.rst b/doc/source/gerrit.rst
index 7040e9ddbc..7e21ae9409 100644
--- a/doc/source/gerrit.rst
+++ b/doc/source/gerrit.rst
@@ -501,11 +501,11 @@ or manually update their remotes with something like::
 Third-Party Testing Access
 --------------------------
 
-The command to add an account for an automated system which gets
--1/+1 code verify voting rights (as outlined in `Third Party
-Testing`_) looks like:
+The command to add an account for an automated system which gets -1/+1
+code verify voting rights (as outlined in :ref:`third-party-testing`)
+looks like:
 
-.. code-block:: shell
+.. code-block:: bash
 
   ssh -p 29418 review.openstack.org "gerrit create-account \
       --group 'Third-Party CI' \
@@ -517,8 +517,6 @@ Testing`_) looks like:
 Details on the create-account_ command can be found in the Gerrit
 API documentation.
 
-.. _`Third-Party CI`: http://ci.openstack.org/third_party.html
-
 .. _create-account: https://review.openstack.org/Documentation/cmd-create-account.html
 
 Resetting a Username in Gerrit
diff --git a/doc/source/logstash.rst b/doc/source/logstash.rst
index 788b985f0c..bc7525fe63 100644
--- a/doc/source/logstash.rst
+++ b/doc/source/logstash.rst
@@ -271,7 +271,10 @@ In the OpenStack logstash system, crm114 attaches an error_pr attribute
 to all indexed entries.  Values from -1000.00 to -10.00 should be considered
 sufficient to get all potential errors as identified by the program.
 Used in a kibana query, it would be structured like this:
-   * ``error_pr:["-1000.0" TO "-10.0"]``
+
+::
+
+  error_pr:["-1000.0" TO "-10.0"]
 
 
 This is still an early effort and additional tuning and refinement should
diff --git a/doc/source/openstackid.rst b/doc/source/openstackid.rst
index 7637107fde..d4e89626e2 100644
--- a/doc/source/openstackid.rst
+++ b/doc/source/openstackid.rst
@@ -1,4 +1,5 @@
 :title: OpenstackId
+
 ==================
 OpenstackId Server
 ==================
@@ -37,15 +38,15 @@ you must make a copy and rename it to bootstrap/environment.php
 In this file you will find an **$app->detectEnvironment** call. The array passed to this method is
 used to determine the current environment. You may add other environments and machine names to the array as needed.
 
-.. code:: php
+.. code-block:: php
 
-<?php
+   <?php
 
-$env = $app->detectEnvironment(array(
+   $env = $app->detectEnvironment(array(
 
-    'local' => array('your-machine-name'),
+       'local' => array('your-machine-name'),
 
-));
+   ));
 
 Database Configuration
 ______________________
diff --git a/doc/source/running-your-own.rst b/doc/source/running-your-own.rst
index d6837da565..8d12d276e2 100644
--- a/doc/source/running-your-own.rst
+++ b/doc/source/running-your-own.rst
@@ -235,15 +235,17 @@ can now set up a scheduler.  Once setup, new patches uploaded
 to gerrit should be picked up and have a zuul verification fail (with 'LOST'
 which indicates the Jenkins environment is gone).
 
-#. Create a zuul user (the upstream site.pp uses jenkins for historical reasons)::
+#. Create a zuul user (the upstream site.pp uses jenkins for historical reasons):
 
-  ssh-keygen -t rsa -P '' -f zuul_ssh_key
+   ::
 
-  cat zuul_ssh_key.pub | ssh -p 29418 $USER@$HOST gerrit create-account \
-    --group "'Continuous Integration Tools'" \
-    --full-name "'Zuul'" \
-    --email zuul@lists.openstack.org \
-    --ssh-key - zuul
+     ssh-keygen -t rsa -P '' -f zuul_ssh_key
+
+     cat zuul_ssh_key.pub | ssh -p 29418 $USER@$HOST gerrit create-account \
+       --group "'Continuous Integration Tools'" \
+       --full-name "'Zuul'" \
+       --email zuul@lists.openstack.org \
+       --ssh-key - zuul
 
 #. Add the private key you made to hiera as ``zuul_ssh_private_key_contents``.
 
@@ -280,9 +282,11 @@ important). When doing bring-up, bringing up jenkins01 first is probably
 best as that is the first of the horizontally-scalable untrusted masters,
 which get the most load (as they run jobs from anyone).
 
-#. Make a jenkins master ssh key (shared across all jenkins masters)::
+#. Make a jenkins master ssh key (shared across all jenkins masters):
 
-  ssh-keygen -t rsa -P '' -f jenkins_ssh_key
+   ::
+
+     ssh-keygen -t rsa -P '' -f jenkins_ssh_key
 
 #. Make a self signed certificate for the jenkins site.
 
diff --git a/doc/source/stackforge.rst b/doc/source/stackforge.rst
index c47bb09826..5af4f73fca 100644
--- a/doc/source/stackforge.rst
+++ b/doc/source/stackforge.rst
@@ -1,5 +1,7 @@
 :title: StackForge
 
+.. _stackforge:
+
 StackForge
 ##########
 
diff --git a/doc/source/systems.rst b/doc/source/systems.rst
index ec034f1e83..80b604c10c 100644
--- a/doc/source/systems.rst
+++ b/doc/source/systems.rst
@@ -28,4 +28,14 @@ Major Systems
    git
    openstackid
 
+.. NOTE(dhellmann): These projects were not listed above, or in any
+   other toctree, which breaks the build. It's not clear why they were
+   left out of the toctree but remained in the source dir. Rather than
+   deleting them, I've added them to a hidden toctree to eliminate
+   that build error.
 
+.. toctree::
+   :hidden:
+
+   activity
+   asterisk
diff --git a/doc/source/third_party.rst b/doc/source/third_party.rst
index f98162bc8b..e450ffadf0 100644
--- a/doc/source/third_party.rst
+++ b/doc/source/third_party.rst
@@ -1,3 +1,5 @@
+.. _third-party-testing:
+
 Third Party Testing
 ===================
 
@@ -44,7 +46,7 @@ Requirements
     <https://wiki.openstack.org/wiki/ThirdPartySystems>`_ to add your
     system.  When complete, there should be a page dedicated to your
     system with a URL like:
-    <https://wiki.openstack.org/wiki/ThirdPartySystems/Example>.
+    ``https://wiki.openstack.org/wiki/ThirdPartySystems/Example``.
   * All comments from your CI system must contain a link to the wiki
     page for your CI system.
   * Maintainers are encouraged to be in IRC regularly to make it faster to contact them.
@@ -64,7 +66,8 @@ Requirements
 
     * logs must be browsable; logs requiring download, installation or login
       to access are not acceptable
-  Note: all test artifacts must be retained for one month.
+
+  .. note:: All test artifacts must be retained for one month.
 
 Reading the Event Stream
 ------------------------
@@ -177,9 +180,11 @@ processes described in this document.  So if your testing system is Jenkins
 based you can use it to simplify things.  You will still need an account to do
 this as described in the :ref:`request-account-label` section above.
 
-The Gerrit Trigger plugin for Jenkins can be found on
-`the Jenkins repository <http://repo.jenkins-ci.org/repo/com/sonyericsson/hudson/plugins/gerrit/gerrit-trigger/>`_.
-You can install it using the Advanced tab in the Jenkins Plugin Manager.
+The Gerrit Trigger plugin for Jenkins can be found on `the Jenkins
+repository`_.  You can install it using the Advanced tab in the
+Jenkins Plugin Manager.
+
+.. _the Jenkins repository: http://repo.jenkins-ci.org/repo/com/sonyericsson/hudson/plugins/gerrit/gerrit-trigger/
 
 Once installed Jenkins will have a new `Gerrit Trigger` option in the `Manage
 Jenkins` menu.  This should be given the following options::
@@ -246,9 +251,11 @@ Permissions on your Third Party System
 When your CI account is created it will be in the `Third-Party CI Gerrit
 group <https://review.openstack.org/#/admin/groups/270,members>`_.
 The permissions on this group allow for commenting and voting on the
-`openstack-dev/sandbox <https://git.openstack.org/cgit/openstack-dev/sandbox/>`_
+`openstack-dev/sandbox`_
 repo as well as commenting without voting on other repos in gerrit.
 
+.. _openstack-dev/sandbox: https://git.openstack.org/cgit/openstack-dev/sandbox/
+
 The OpenStack Infrastructure team disables mis-behaving third-party ci
 accounts at its discretion. This documentation endeavours to outline specific
 circumstances that may lead to an account being disabled. There have been
@@ -273,9 +280,11 @@ chance of success if you follow these steps:
 
   * send an email to the openstack-dev mailing list nominating your system for voting
     permissions
+
       * openstack-dev@lists.openstack.org
       * use tags [Infra][Nova] for the Nova program, please replace [Nova] with [Program],
         where [Program] is the name of the program your CI account will test
+
   * present your account history
   * address any questions and concerns with your system
 
diff --git a/setup.cfg b/setup.cfg
index 8019e24b1b..b85de267ac 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -18,3 +18,6 @@ classifier =
 all_files = 1
 build-dir = doc/build
 source-dir = doc/source
+
+[pbr]
+warnerrors = true
diff --git a/tox.ini b/tox.ini
index 34f9788932..a84b0f7d1e 100644
--- a/tox.ini
+++ b/tox.ini
@@ -28,6 +28,9 @@ commands = {toxinidir}/tools/check_projects_yaml_alphabetized.sh
 [testenv:venv]
 commands = {posargs}
 
+[testenv:docs]
+commands = python setup.py build_sphinx
+
 [testenv:irc]
 deps = PyYAML
      irc