diff --git a/tools/sphinx8 b/tools/sphinx8 new file mode 100755 index 000000000..d6a9290c2 --- /dev/null +++ b/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()) diff --git a/tox.ini b/tox.ini index 4d3418e31..379329aff 100644 --- a/tox.ini +++ b/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}