Allow Sphinx doctests to run and pass with `make doctest SPHINXBUILD=$VENV/bin/sphinx-build`.

- TODO: two tests in `docs/narr/hooks.rst`

4 files changed, 83 insertions, 42 deletions

diff --git a/abc.py b/abc.py
new file mode 100644
index 000000000..c200d64c5
--- /dev/null
+++ b/abc.py
@@ -0,0 +1,18 @@
+from pyramid import testing
+from pyramid.config import Configurator
+
+
+def total(request, *args):
+    return sum(args)
+
+
+def prop(request):
+    print("getting the property")
+    return "the property"
+
+
+config = Configurator()
+config.add_request_method(total)
+config.add_request_method(prop, reify=True)
+
+request = testing.DummyRequest()
diff --git a/docs/Makefile b/docs/Makefile
index 546deb30a..411ff35df 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -12,16 +12,20 @@ PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
+.PHONY: help clean html text web pickle htmlhelp latex latexpdf changes linkcheck epub doctest
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html      to make standalone HTML files"
-	@echo "  pickle    to make pickle files (usable by e.g. sphinx-web)"
-	@echo "  htmlhelp  to make HTML files and a HTML help project"
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  changes   to make an overview over all changed/added/deprecated items"
-	@echo "  linkcheck to check all external links for integrity"
+	@echo "  html       to make standalone HTML files"
+	@echo "  text       to make text files"
+	@echo "  pickle     to make pickle files (usable by e.g. sphinx-web)"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  changes    to make an overview over all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  epub       to make an epub"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
 	-rm -rf $(BUILDDIR)/*
@@ -90,3 +94,7 @@ epub:
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index 7e961f5e8..a1319e45f 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -260,19 +260,28 @@ added to the flash queue, and empties the queue.
 
 .. method:: pop_flash(queue='')
 
->>> request.session.flash('info message')
->>> request.session.pop_flash()
-['info message']
+.. testsetup::
+
+   from pyramid import testing
+   request = testing.DummyRequest()
+
+.. doctest::
+
+   >>> request.session.flash('info message')
+   >>> request.session.pop_flash()
+   ['info message']
 
 Calling ``session.pop_flash()`` again like above without a corresponding call
 to ``session.flash()`` will return an empty list, because the queue has already
 been popped.
 
->>> request.session.flash('info message')
->>> request.session.pop_flash()
-['info message']
->>> request.session.pop_flash()
-[]
+.. doctest::
+
+   >>> request.session.flash('info message')
+   >>> request.session.pop_flash()
+   ['info message']
+   >>> request.session.pop_flash()
+   []
 
 .. index::
    single: session.peek_flash
@@ -287,15 +296,17 @@ flash storage.
 
 .. method:: peek_flash(queue='')
 
->>> request.session.flash('info message')
->>> request.session.peek_flash()
-['info message']
->>> request.session.peek_flash()
-['info message']
->>> request.session.pop_flash()
-['info message']
->>> request.session.peek_flash()
-[]
+.. doctest::
+
+   >>> request.session.flash('info message')
+   >>> request.session.peek_flash()
+   ['info message']
+   >>> request.session.peek_flash()
+   ['info message']
+   >>> request.session.pop_flash()
+   ['info message']
+   >>> request.session.peek_flash()
+   []
 
 .. index::
    single: preventing cross-site request forgery attacks
diff --git a/pyramid/decorator.py b/pyramid/decorator.py
index 72c8b3800..ea518bfcb 100644
--- a/pyramid/decorator.py
+++ b/pyramid/decorator.py
@@ -8,28 +8,32 @@ class reify(object):
     replacing the function it decorates with an instance variable.  It is, in
     Python parlance, a non-data descriptor.  An example:
 
-    .. code-block:: python
+    .. testsetup::
 
-       class Foo(object):
-           @reify
-           def jammy(self):
-               print('jammy called')
-               return 1
+        from pyramid.decorator import reify
+
+        class Foo(object):
+            @reify
+            def jammy(self):
+                print('jammy called')
+                return 1
 
     And usage of Foo:
 
-    >>> f = Foo()
-    >>> v = f.jammy
-    'jammy called'
-    >>> print(v)
-    1
-    >>> f.jammy
-    1
-    >>> # jammy func not called the second time; it replaced itself with 1
-    >>> # Note: reassignment is possible
-    >>> f.jammy = 2
-    >>> f.jammy
-    2
+    .. doctest::
+
+        >>> f = Foo()
+        >>> v = f.jammy
+        jammy called
+        >>> print(v)
+        1
+        >>> f.jammy
+        1
+        >>> # jammy func not called the second time; it replaced itself with 1
+        >>> # Note: reassignment is possible
+        >>> f.jammy = 2
+        >>> f.jammy
+        2
     """
     def __init__(self, wrapped):
         self.wrapped = wrapped