Enable the sphinx doctest extension.

docs/Makefile

@@ -23,5 +23,9 @@ latex:
 pdf: latex
 	cd build/latex && pdflatex -interaction=nonstopmode tornado.tex
 
+.PHONY: doctest
+doctest:
+	sphinx-build -b doctest $(SPHINXOPTS) build/doctest
+
 clean:
 	rm -rf build

docs/conf.py

@@ -14,6 +14,7 @@ version = release = tornado.version
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.coverage",
+    "sphinx.ext.doctest",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",

docs/httputil.rst

@@ -1,5 +1,9 @@
 ``tornado.httputil`` --- Manipulate HTTP headers and URLs
 =========================================================
 
+.. testsetup::
+
+   from tornado.httputil import *
+
 .. automodule:: tornado.httputil
    :members:

docs/util.rst

@@ -1,5 +1,9 @@
 ``tornado.util`` --- General-purpose utilities
 ==============================================
 
+.. testsetup::
+
+   from tornado.util import *
+
 .. automodule:: tornado.util
     :members:

tox.ini

@@ -44,7 +44,10 @@ envlist =
         {py27,py3}-unittest2,
 
         # Ensure the sphinx build has no errors or warnings
-        py3-docs
+        py3-sphinx-docs,
+        # Run the doctests via sphinx (which covers things not run
+        # in the regular test suite and vice versa)
+        {py2,py3}-sphinx-doctest
 
 [testenv]
 # Most of these are defaults, but if you specify any you can't fall back
@@ -87,6 +90,8 @@ deps =
      py33-asyncio: asyncio
      trollius: trollius
      py2-monotonic: Monotime
+     sphinx: sphinx
+     sphinx: sphinx_rtd_theme
 
 setenv =
        # The extension is mandatory on cpython.
@@ -139,13 +144,22 @@ changedir = {toxworkdir}
 # Remove it (it's not a part of {opts}) to only install real releases.
 install_command = pip install {opts} {packages}
 
-[testenv:py3-docs]
+[testenv:py3-sphinx-docs]
 changedir = docs
 # For some reason the extension fails to load in this configuration,
 # but it's not really needed for docs anyway.
 setenv = TORNADO_EXTENSION=0
-deps =
-     sphinx==1.2.2
-     sphinx_rtd_theme
 commands =
     sphinx-build -q -E -n -W -b html . {envtmpdir}/html
+
+[testenv:py2-sphinx-doctest]
+changedir = docs
+setenv = TORNADO_EXTENSION=0
+commands =
+     sphinx-build -q -E -n -W -b doctest . {envtmpdir}/doctest
+
+[testenv:py3-sphinx-doctest]
+changedir = docs
+setenv = TORNADO_EXTENSION=0
+commands =
+     sphinx-build -q -E -n -W -b doctest . {envtmpdir}/doctest