From b29d7c33db5a796778ae477329306e4f4531725a Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Sat, 15 Oct 2016 17:53:48 -0400 Subject: [PATCH] Enable doctesting of ReST docs with `make doctest`. --- doc/README.rst | 65 ++++++++++++++++++++++++---------------------- doc/makefile | 8 +----- doc/source/conf.py | 8 +++++- makefile | 4 +++ 4 files changed, 46 insertions(+), 39 deletions(-) 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 ' where 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 -- 2.43.2