Update tox 'docs' environment to test specs

This commit updates the tox 'docs' environment to also run our specs
tests, so that the existing docs gate merge jobs will catch any specs
that get added but don't follow the template.

This commit also updates the specs test to suppress warnings for
:doc: references in specs.

Change-Id: Ie7dda124a0c964712b1a02b55730a76fa346111e
Closes-Bug: #1621648

specs-tests/test_titles.py

@@ -15,6 +15,7 @@ import glob
 import docutils.core
 from docutils.parsers import rst
 from docutils.parsers.rst import directives
+from docutils.parsers.rst import roles
 import testtools
 
 
@@ -25,11 +26,17 @@ class FakeDirective(rst.Directive):
         return []
 
 
+def fake_role(name, rawtext, text, lineno, inliner,
+              options=None, content=None):
+    return [], []
+
+
 directives.register_directive('seqdiag', FakeDirective)
 directives.register_directive('blockdiag', FakeDirective)
 directives.register_directive('nwdiag', FakeDirective)
 directives.register_directive('actdiag', FakeDirective)
 directives.register_directive('graphviz', FakeDirective)
+roles.register_local_role('doc', fake_role)
 
 
 class TestTitles(testtools.TestCase):

tox.ini

@@ -46,6 +46,8 @@ commands = flake8
 [testenv:docs]
 commands =
     python setup.py build_sphinx
+    find . -type f -name "*.pyc" -delete
+    python -m unittest specs-tests.test_titles
 
 [testenv:venv]
 commands = {posargs}