Enable doctesting of ReST docs with `make doctest`.

diff --git a/doc/README.rst b/doc/README.rst
index 46407670a2ad0b3d57a9ec8cff98a9f792c1f186..71876c6271b7912198acd51aa41afef0f7ef6adc 100644 (file)
--- a/doc/README.rst
+++ b/doc/README.rst
@@ -63,40 +63,43 @@ game over both of those cones.
 
 First, we use the nonnegative orthant in :math:`\mathbb{R}^{2}`:
 
->>> from dunshire import *
->>> K = NonnegativeOrthant(2)
->>> L = [[1,0],[0,1]]
->>> e1 = [1,1]
->>> e2 = e1
->>> G = SymmetricLinearGame(L,K,e1,e2)
->>> print(G.solution())
-Game value: 0.5000000
-Player 1 optimal:
-  [0.5000000]
-  [0.5000000]
-Player 2 optimal:
-  [0.5000000]
-  [0.5000000]
+.. doctest::
+
+  >>> from dunshire import *
+  >>> K = NonnegativeOrthant(2)
+  >>> L = [[1,0],[0,1]]
+  >>> e1 = [1,1]
+  >>> e2 = e1
+  >>> G = SymmetricLinearGame(L,K,e1,e2)
+  >>> print(G.solution())
+  Game value: 0.5000000
+  Player 1 optimal:
+    [0.5000000]
+    [0.5000000]
+  Player 2 optimal:
+    [0.5000000]
+    [0.5000000]
 
 Next we try the Lorentz ice-cream cone in :math:`\mathbb{R}^{2}`:
 
->>> from dunshire import *
->>> K = IceCream(2)
->>> L = [[1,0],[0,1]]
->>> e1 = [1,1]
->>> e2 = e1
->>> G = SymmetricLinearGame(L,K,e1,e2)
->>> print(G.solution())
-Game value: 0.5000000
-Player 1 optimal:
-  [0.5000000]
-  [0.5000000]
-Player 2 optimal:
-  [0.5000000]
-  [0.5000000]
-
-(The answer when :math:`L`, :math:`e_{1}`, and :math:`e_{2}` are so
-simple is independent of the cone.)
+.. doctest::
+
+  >>> from dunshire import *
+  >>> K = IceCream(2)
+  >>> L = [[1,0],[0,1]]
+  >>> e1 = [1,1]
+  >>> e2 = e1
+  >>> G = SymmetricLinearGame(L,K,e1,e2)
+  >>> print(G.solution())
+  Game value: 0.5000000
+  Player 1 optimal:
+    [0.8347039]
+    [0.1652961]
+  Player 2 optimal:
+    [0.5000000]
+    [0.5000000]
+
+Note that these solutions are not unique, although the game values are.
 
 Requirements
 ------------

diff --git a/doc/makefile b/doc/makefile
index 42f9f160cf306be4d158884a5fac7b237101182b..2b056c585581e5874bfdf90bab4e4a3a963fefa0 100644 (file)
--- a/doc/makefile
+++ b/doc/makefile
@@ -19,7 +19,7 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sou
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 
 help:
        @echo "Please use \`make <target>' where <target> is one of"
@@ -46,7 +46,6 @@ help:
        @echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
        @echo "  linkcheck  to check all external links for integrity"
        @echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-       @echo "  coverage   to run coverage check of the documentation (if enabled)"
 
 clean:
        rm -rf $(BUILDDIR)/*
@@ -176,11 +175,6 @@ doctest:
        @echo "Testing of doctests in the sources finished, look at the " \
              "results in $(BUILDDIR)/doctest/output.txt."
 
-coverage:
-       $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
-       @echo "Testing of coverage in the sources finished, look at the " \
-             "results in $(BUILDDIR)/coverage/python.txt."
-
 xml:
        $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
        @echo

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 673323100730a2185be349bda90b96759b8f03da..63ffa74cf3ee48390a75559a91d6002c92e3d55c 100644 (file)
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -16,7 +16,7 @@ sys.path.insert(0, os.path.abspath('../../src/dunshire'))
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
-    'sphinx.ext.coverage',
+    'sphinx.ext.doctest',
     'sphinx.ext.napoleon',
     'sphinx.ext.pngmath',
     'sphinx.ext.viewcode',
@@ -24,6 +24,12 @@ extensions = [
 
 autosummary_generate = True
 
+# Don't automatically test every >>> block in the documentation. This
+# avoids testing the API docs as part of the documentation build,
+# which is exactly what we intend, because those are tested as part of
+# the (much faster) unittest test suite.
+doctest_test_doctest_blocks = ''
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']

diff --git a/makefile b/makefile
index b8a02711b3b0a9f63c0deacb8bc8ad7700e80e6f..511f2cc0fa17b948aeaca578c3331ad18c5b5502 100644 (file)
--- a/makefile
+++ b/makefile
@@ -6,6 +6,10 @@ doc: $(SRCS) doc/source/conf.py doc/makefile
        sphinx-apidoc -f -o doc/source $(SRCDIR)
        cd doc && $(MAKE) html
 
+.PHONY: doctest
+doctest:
+       cd doc && $(MAKE) doctest
+
 .PHONY: check
 check:
        python test/suite.py