Update doc build to fail if there are warnings

Update the documentation build to use a tox environment and pass
through pbr and to use the flag to have the build fail if there are
any warnings.

Fix existing warnings in the documentation by adding a glossary with two
referenced terms and correcting a few other minor issues.

Change-Id: I082d8d73debca891811fb2f0c1116f9bf5bee54e

Author: dhellmann

Makefile

@@ -18,7 +18,7 @@ sdist: html
 # Documentation
 .PHONY: html
 html:
-	(cd docs && $(MAKE) html)
+	tox -e docs
 
 .PHONY: docclean
 docclean:

docs/source/command_ref.rst

@@ -413,6 +413,8 @@ Syntax::
 Path Management
 ===============
 
+.. _command-add2virtualenv:
+
 add2virtualenv
 --------------
 

docs/source/glossary.rst

@@ -0,0 +1,16 @@
+==========
+ Glossary
+==========
+
+.. glossary::
+
+  project directory
+
+    Directory associated with a virtualenv, usually located elsewhere
+    and containing more permanent development artifacts such as local
+    source files, test data, etc. (see :ref:`variable-PROJECT_HOME`)
+
+  template
+
+    Input to :ref:`command-mkproject` that configures the *project
+    directory* to contain default files. (see :ref:`plugins`)

docs/source/history.rst

@@ -327,8 +327,7 @@ run in the same place as before.
   - Implement suggestion by Van Lindberg to have
     :ref:`VIRTUALENVWRAPPER_HOOK_DIR
     <variable-VIRTUALENVWRAPPER_HOOK_DIR>` and
-    :ref:`VIRTUALENVWRAPPER_LOG_DIR
-    <variable-VIRTUALENVWRAPPER_LOG_DIR>` variables to control the
+    ``VIRTUALENVWRAPPER_LOG_DIR`` variables to control the
     locations of hooks and logs.
   - Enabled tab completion for :ref:`command-showvirtualenv`
     (:bbissue:`78`).

docs/source/index.rst

@@ -181,6 +181,7 @@ Details
    extensions
    design
    history
+   glossary
 
 .. _references:
 

setup.cfg

@@ -72,3 +72,6 @@ virtualenvwrapper.post_deactivate_source =
     user_scripts = virtualenvwrapper.user_scripts:post_deactivate_source
 virtualenvwrapper.get_env_details =
     user_scripts = virtualenvwrapper.user_scripts:get_env_details
+
+[pbr]
+warnerrors = true

tox.ini

@@ -47,3 +47,10 @@ basepython=python2.7
 setenv =
   SHELL = /bin/ksh
 commands =  ksh ./tests/run_tests {envdir} []
+
+[testenv:docs]
+basepython=python2.7
+deps =
+  -r{toxinidir}/requirements.txt
+  -r{toxinidir}/docs/requirements.txt
+commands = python setup.py build_sphinx