From: Michael Orlitzky <michael@orlitzky.com>
Date: Sat, 15 Oct 2016 21:53:48 +0000 (-0400)
Subject: Enable doctesting of ReST docs with `make doctest`.
X-Git-Tag: 0.1.0~132
X-Git-Url: https://gitweb.michael.orlitzky.com/?a=commitdiff_plain;h=b29d7c33db5a796778ae477329306e4f4531725a;p=dunshire.git

Enable doctesting of ReST docs with `make doctest`.
---

diff --git a/doc/README.rst b/doc/README.rst
index 4640767..71876c6 100644
--- 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 42f9f16..2b056c5 100644
--- 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 6733231..63ffa74 100644
--- 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 b8a0271..511f2cc 100644
--- 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