Add CI job to check docs including doctest

Fixes #1027, #1028

Author: cburgdorf

.circleci/config.yml

@@ -52,6 +52,12 @@ jobs:
       - image: circleci/python:3.6
         environment:
           TOXENV: lint-py36
+  py36-docs:
+    <<: *common
+    docker:
+      - image: circleci/python:3.6
+        environment:
+          TOXENV: py36-docs
   py35-native-state-byzantium:
     <<: *common
     docker:
@@ -243,6 +249,7 @@ workflows:
   version: 2
   test:
     jobs:
+      - py36-docs
       - py36-native-state-byzantium
       - py36-native-state-frontier
       - py36-native-state-homestead

Makefile

@@ -40,6 +40,11 @@ coverage:
 build-docs:
 	cd docs/; sphinx-build -T -E . _build/html
 
+doctest:
+	cd docs/; sphinx-build -T -b doctest . _build/doctest
+
+validate-docs: build-docs doctest
+
 docs: build-docs
 	open docs/_build/html/index.html
 

docs/conf.py

@@ -41,6 +41,7 @@
 extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinxcontrib.asyncio',
 ]
@@ -180,3 +181,14 @@
     'python': ('https://docs.python.org/3.5', None),
     'eth-typing': ('https://eth-typing.readthedocs.io/en/latest', None),
 }
+
+# -- Doctest configuration ----------------------------------------
+
+import doctest
+
+doctest_default_flags = (0
+    | doctest.DONT_ACCEPT_TRUE_FOR_1
+    | doctest.ELLIPSIS
+    | doctest.IGNORE_EXCEPTION_DETAIL
+    | doctest.NORMALIZE_WHITESPACE
+)

tox.ini

@@ -47,6 +47,18 @@ basepython =
     py36: python3.6
 
 
+[testenv:py36-docs]
+whitelist_externals=
+    make
+deps = .[doc]
+basepython=python3.6
+passenv =
+    PYTEST_ADDOPTS
+    TRAVIS_EVENT_TYPE
+commands=
+    make validate-docs
+
+
 [testenv:py36-trinity-integration]
 deps = .[eth-extras, test]
 basepython=python3.6