Add sphinx8, a thin wrapper around doc8 that supports sphinx

tools/sphinx8

@@ -0,0 +1,31 @@
+#!/usr/bin/env python
+
+"""
+Sphinx documentation style checker.
+
+This is a very thin wrapper around doc8, that adds support for sphinx-specific
+RST directives.
+
+NOTE: We require sphinx>1.5 in order to avoid automatically registering all
+directives when any of the directives modules are imported.
+"""
+
+import sys
+
+import doc8.main
+import sphinx.directives
+import sphinx.directives.code
+import sphinx.directives.patches
+
+
+def main():
+    # NOTE: Registering sphinx.directives.other causes a failure in parsing
+    # later.
+    sphinx.directives.setup(None)
+    sphinx.directives.code.setup(None)
+    sphinx.directives.patches.setup(None)
+    return doc8.main.main()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tox.ini

@@ -17,7 +17,13 @@ commands = unit2 discover {posargs}
 commands =
   flake8 {posargs}
   # Check the *.rst files
-  doc8 README.rst CONTRIBUTING.rst doc/source --ignore D001
+  # We use a thin wrapper around doc8 currently, which has support for sphinx
+  # directives. We install sphinx 1.5.x because versions prior to this
+  # (installed due to upper constraints) automatically import all
+  # sphinx.directive.* modules when any one of those modules is imported, and
+  # importing sphinx.directive.other breaks docutils parsing.
+  pip install -U sphinx<1.6
+  {toxinidir}/tools/sphinx8 README.rst CONTRIBUTING.rst doc/source --ignore D001
 
 [testenv:venv]
 commands = {posargs}