Doc cleanup

Turn on warnerrors and fix the errors it reports.

Change-Id: I92a194e47b97dbdeb0e72164a813f41914f4f298

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

doc/source/elastic-recheck.rst

@@ -3,7 +3,7 @@
 .. _elastic-recheck:
 
 Elastic-Recheck
-######
+###############
 
 
 

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

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

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
 ______________________

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.
 

doc/source/stackforge.rst

@@ -1,5 +1,7 @@
 :title: StackForge
 
+.. _stackforge:
+
 StackForge
 ##########
 

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

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
 

setup.cfg

@@ -18,3 +18,6 @@ classifier =
 all_files = 1
 build-dir = doc/build
 source-dir = doc/source
+
+[pbr]
+warnerrors = true

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