Merge pull request #2530 from stevepiercy/master

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

5 files changed, 124 insertions, 47 deletions

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/hooks.rst b/docs/narr/hooks.rst
index b776f99e8..150eca944 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -300,13 +300,38 @@ added as a property and its result is cached per-request by setting
 ``reify=True``. This way, we eliminate the overhead of running the function
 multiple times.
 
+.. testsetup:: group1
+
+   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)
+   config.commit()
+
+   from pyramid.scripting import prepare
+   request = prepare(registry=config.registry)["request"]
+
+.. doctest:: group1
+
    >>> request.total(1, 2, 3)
    6
    >>> request.prop
    getting the property
-   the property
+   'the property'
    >>> request.prop
-   the property
+   'the property'
 
 To not cache the result of ``request.prop``, set ``property=True`` instead of
 ``reify=True``.
@@ -338,13 +363,42 @@ Here is an example of passing a class to ``Configurator.add_request_method``:
 
 We attach and cache an object named ``extra`` to the ``request`` object.
 
+.. testsetup:: group2
+
+   from pyramid.config import Configurator
+   from pyramid.decorator import reify
+
+   class ExtraStuff(object):
+
+       def __init__(self, request):
+           self.request = request
+
+       def total(self, *args):
+           return sum(args)
+
+       # use @property if you don't want to cache the result
+       @reify
+       def prop(self):
+           print("getting the property")
+           return "the property"
+
+   config = Configurator()
+   config.add_request_method(ExtraStuff, 'extra', reify=True)
+   config.commit()
+
+   from pyramid.scripting import prepare
+   request = prepare(registry=config.registry)["request"]
+
+.. doctest:: group2
+
    >>> request.extra.total(1, 2, 3)
    6
    >>> request.extra.prop
    getting the property
-   the property
+   'the property'
    >>> request.extra.prop
-   the property
+   'the property'
+
 
 .. index::
    single: response factory
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
diff --git a/tox.ini b/tox.ini
index 258b2892c..fc47faf17 100644
--- a/tox.ini
+++ b/tox.ini
@@ -57,7 +57,7 @@ basepython = python3.5
 whitelist_externals = make
 commands =
     pip install pyramid[docs]
-    make -C docs html epub BUILDDIR={envdir} "SPHINXOPTS=-W -E"
+    make -C docs doctest html epub BUILDDIR={envdir} "SPHINXOPTS=-W -E"
 
 # we separate coverage into its own testenv because a) "last run wins" wrt
 # cobertura jenkins reporting and b) pypy and jython can't handle any