add doctest by default

Makefile

@@ -38,6 +38,7 @@ build-docs:
 	sphinx-apidoc -o docs/ . setup.py "*conftest*"
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
+	$(MAKE) -C docs doctest
 
 docs: build-docs
 	open docs/_build/html/index.html

docs/conf.py

@@ -34,7 +34,11 @@ with open (os.path.join(DIR, '../setup.py'), 'r') as f:
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -271,3 +275,14 @@ texinfo_documents = [
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3.5', 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

@@ -2,6 +2,7 @@
 envlist=
     py{35,36,py3}-core
     lint
+    doctest
 
 [isort]
 combine_as_imports=True
@@ -22,11 +23,14 @@ ignore=
 usedevelop=True
 commands=
     core: py.test {posargs:tests/core}
+    doctest: make -C {toxinidir}/docs doctest
 basepython =
     py35: python3.5
     py36: python3.6
     pypy3: pypy3
-extras=test
+extras=
+    test
+    doctest: doc
 
 [testenv:lint]
 basepython=python