doc image generation: revise Makefile and generate_diffs

The Makefile now does not require any maintenance when adding/removing images
and tutorial scripts.  generate_diffs only overwrites diffs if they have
changed.

TODO

@@ -80,7 +80,4 @@ Roughly in order of importance.                                     -*-org-*-
 * Adopt mincut/maxflow algorithm from networkx or python-graph to find the best
   representation of a lead unit cell.
 
-* Improve logic of generate_diffs.sh
-  Do not overwrite the diffs that do not need to be updated.
-
 * Tutorial choose either "A [B]" or "A in units of B" consistently.

doc/Makefile

@@ -19,27 +19,22 @@ PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
-# In difference to the original Makefile, we convert all SVG files to PDF for
-# LaTeX output.  For HTML output, we don't create PNGs but rather use the SVG
-# files directly.
+# We convert all SVG files to PDF for LaTeX output.  For HTML output, we don't
+# create PNGs but rather use the SVG files directly.
 IMAGESOURCES    = $(shell find source -name "*.svg")
-GENERATEDPDF    = $(patsubst %.svg, %.pdf, $(IMAGESOURCES))
-
-expand = $(foreach name, $(foreach fig, $(2), $(1)_$(fig)), \
-source/images/$(name).png source/images/$(name).pdf)
-
-# Generated images.
-1_IMAGES = $(call expand, quantum_wire, result sys)
-2A_IMAGES = $(call expand, spin_orbit, result)
-2B_IMAGES = $(call expand, quantum_well, result)
-2C_IMAGES = $(call expand, ab_ring, result sys note1 note2)
-3A_IMAGES = $(call expand, band_structure, result)
-3B_IMAGES = $(call expand, closed_system, result sys)
-4_IMAGES = $(call expand, graphene, result sys1 sys2 bs)
-5A_IMAGES = $(call expand, superconductor_band_structure, result)
-5B_IMAGES = $(call expand, superconductor_transport, result)
-ALL_IMAGES = $(1_IMAGES)  $(2A_IMAGES) $(2B_IMAGES) $(2C_IMAGES) $(3A_IMAGES) \
-$(3B_IMAGES) $(4_IMAGES) $(5A_IMAGES) $(5B_IMAGES)
+GENERATEDPDF    = $(patsubst %.svg,%.pdf,$(IMAGESOURCES))
+
+# Image generation from patched tutorial scripts
+#
+# As make does not support the generation of multiple targets by a single
+# invocation of a (non-implicit) rule, we use a trick: We pretend to be
+# generating a single (empty) flag file per invocation.  The image files are
+# generated as well, but only as side-effects.  Each flag file is used to
+# remember the time at which the corresponding image-generating script was run.
+# This works perfectly unless the actual output files are deleted without
+# deleting the corresponding flag file.
+SCRIPTS = $(patsubst source/images/%.diff,%,$(wildcard source/images/*.py.diff))
+FLAGS = $(patsubst %.py,source/images/.%_flag,$(SCRIPTS))
 
 .PHONY: help clean realclean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
 
@@ -61,35 +56,38 @@ clean:
 	-rm -rf source/reference/generated
 
 realclean: clean
-	-rm -f $(ALL_IMAGES) source/images/.*_flag source/images/[a-zA-Z]*.py
+	-rm -f $(FLAGS)
+	-rm -f $(patsubst %,source/images/%,$(SCRIPTS))
+	-rm -f $(patsubst %.py,source/images/%_*.png,$(SCRIPTS))
+	-rm -f $(patsubst %.py,source/images/%_*.pdf,$(SCRIPTS))
 
-html:	$(ALL_IMAGES)
+html:	$(FLAGS)
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-dirhtml: $(ALL_IMAGES)
+dirhtml: $(FLAGS)
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
-pickle: $(ALL_IMAGES)
+pickle: $(FLAGS)
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
-json:   $(ALL_IMAGES)
+json:   $(FLAGS)
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
-htmlhelp: $(ALL_IMAGES)
+htmlhelp: $(FLAGS)
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
-qthelp: $(ALL_IMAGES)
+qthelp: $(FLAGS)
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -98,7 +96,7 @@ qthelp: $(ALL_IMAGES)
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/kwant.qhc"
 
-latex:  $(GENERATEDPDF) $(ALL_IMAGES)
+latex:  $(GENERATEDPDF) $(FLAGS)
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@@ -124,43 +122,19 @@ doctest:
 %.pdf: %.svg
 	inkscape --export-pdf=$@ $<
 
-
 # Make the image generation scripts by patching tutorial scipts.
 .SECONDARY:
 %.py: %.py.diff
 	@grep -v '^#HIDDEN' source/tutorial/$(notdir $@) >$@
 	@patch $@ $<
 
-# Generation of tutorial images.  This requires some make trickery, see
-# http://article.gmane.org/gmane.comp.gnu.make.general/5806
+# The image generation scripts depend on their unpatched originals
+define makedep
+source/images/$(1): source/tutorial/$(1)
+endef
+$(foreach name,$(SCRIPTS),$(eval $(call makedep,$(name))))
 
+# Generation of images
 .%_flag: %.py
 	cd $(dir $<) && python $(notdir $<)
 	@touch $@
-
-$(1_IMAGES): source/images/.quantum_wire_flag
-	@:
-
-$(2A_IMAGES): source/images/.spin_orbit_flag
-	@:
-
-$(2B_IMAGES): source/images/.quantum_well_flag
-	@:
-
-$(2C_IMAGES): source/images/.ab_ring_flag
-	@:
-
-$(3A_IMAGES): source/images/.band_structure_flag
-	@:
-
-$(3B_IMAGES): source/images/.closed_system_flag
-	@:
-
-$(4_IMAGES): source/images/.graphene_flag
-	@:
-
-$(5A_IMAGES): source/images/.superconductor_band_structure_flag
-	@:
-
-$(5B_IMAGES): source/images/.superconductor_transport_flag
-	@:

doc/source/images/generate-diffs.sh → doc/source/images/generate-diffs

@@ -4,9 +4,13 @@
 # that are kept under vesion control instead of the scripts themselves.
 
 for f in [a-zA-Z]*.py; do
-    echo $f
     # We use custom labels to suppress the time stamps which are unnecessary
     # here and would only lead to noise in version control.
     grep -v '#HIDDEN' ../tutorial/$f |
-    diff -u --label original --label modified - $f >$f.diff
+    diff -u --label original --label modified - $f >$f.diff_
+    if cmp $f.diff_ $f.diff >/dev/null 2>&1; then
+        rm $f.diff_
+    else
+        mv $f.diff_ $f.diff
+    fi
 done

doc/source/tutorial/README

@@ -7,5 +7,5 @@ and running ``make doc/source/images/SCRIPT.py`` in doc.  Now examine the newly
 created doc/source/images/SCRIPT.py.  If you do not like the result or the
 patch did not apply, edit doc/source/images/SCRIPT.py until you like it.  You
 can run `make html` during your edits to check things.  Finally, even if you
-did not edit the script, execute generate-diffs.sh in doc/source/images.  If
+did not edit the script, execute generate-diffs in doc/source/images.  If
 the patches applied cleanly the diff files will usually stay unchanged.