docs: autogenerate animations, compare with CI (PrincetonUniversity#2104

)

Generating animations used in the docs (currently only
Composition_XOR_animation.gif referenced in composition.py) allows
changes to be monitored with the docs-compare CI. Originally mentioned
in PrincetonUniversity#1861, to allow
updating pillow requirement

.github/workflows/pnl-ci-docs.yml

@@ -94,14 +94,14 @@ jobs:
       run: git tag 'v999.999.999.999'
 
     - name: Build Documentation
-      run: sphinx-build -b html -aE -j auto docs/source pnl-html
+      run: make -C docs/ html -e SPHINXOPTS="-aE -j auto"
 
     - name: Upload Documentation
       uses: actions/[email protected]
       with:
         name: Documentation-${{matrix.pnl-version}}-${{ matrix.os }}-${{ matrix.python-version }}-${{ matrix.python-architecture }}
         retention-days: 1
-        path: pnl-html
+        path: docs/build/html
 
   docs-deploy:
     strategy:

.github/workflows/pnl-docs-compare.yml

@@ -67,13 +67,13 @@ jobs:
       run: git tag 'v999.999.999.999'
 
     - name: Build docs
-      run: sphinx-build -b html -aE -j auto docs/source pnl-html
+      run: make -C docs/ html -e SPHINXOPTS="-aE -j auto"
 
     - name: Upload generated docs
       uses: actions/[email protected]
       with:
         name: docs-${{ matrix.pnl-version }}-${{ matrix.os }}-${{ matrix.python-version }}
-        path: pnl-html
+        path: docs/build/html
         retention-days: 1
 
   docs-compare:

docs/Makefile

@@ -51,44 +51,44 @@ clean:
 	rm -rf $(BUILDDIR)/*
 
 .PHONY: html
-html:
+html: generated
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 .PHONY: dirhtml
-dirhtml:
+dirhtml: generated
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 .PHONY: singlehtml
-singlehtml:
+singlehtml: generated
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
 .PHONY: pickle
-pickle:
+pickle: generated
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
 .PHONY: json
-json:
+json: generated
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
 .PHONY: htmlhelp
-htmlhelp:
+htmlhelp: generated
 	$(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."
 
 .PHONY: qthelp
-qthelp:
+qthelp: generated
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -98,7 +98,7 @@ qthelp:
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PsyNeuLink.qhc"
 
 .PHONY: applehelp
-applehelp:
+applehelp: generated
 	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
 	@echo
 	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@@ -107,7 +107,7 @@ applehelp:
 	      "bundle."
 
 .PHONY: devhelp
-devhelp:
+devhelp: generated
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
@@ -117,80 +117,80 @@ devhelp:
 	@echo "# devhelp"
 
 .PHONY: epub
-epub:
+epub: generated
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 .PHONY: epub3
-epub3:
+epub3: generated
 	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
 	@echo
 	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
 
 .PHONY: latex
-latex:
+latex: generated
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
 .PHONY: latexpdf
-latexpdf:
+latexpdf: generated
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 .PHONY: latexpdfja
-latexpdfja:
+latexpdfja: generated
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through platex and dvipdfmx..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 .PHONY: text
-text:
+text: generated
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
 .PHONY: man
-man:
+man: generated
 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
 .PHONY: texinfo
-texinfo:
+texinfo: generated
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
 	      "(use \`make info' here to do that automatically)."
 
 .PHONY: info
-info:
+info: generated
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILDDIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
 
 .PHONY: gettext
-gettext:
+gettext: generated
 	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
 	@echo
 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
 .PHONY: changes
-changes:
+changes: generated
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
 .PHONY: linkcheck
-linkcheck:
+linkcheck: generated
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
@@ -209,13 +209,13 @@ coverage:
 	      "results in $(BUILDDIR)/coverage/python.txt."
 
 .PHONY: xml
-xml:
+xml: generated
 	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
 	@echo
 	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
 
 .PHONY: pseudoxml
-pseudoxml:
+pseudoxml: generated
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
@@ -239,3 +239,7 @@ gh-pages:
 	git add -A
 	git ci -m "Generated gh-pages for `git log devel -1 --pretty=short --abbrev-commit`" && git push origin gh-pages ; git checkout devel
 	make clean
+
+.PHONY: generated
+generated:
+	find source/generator_scripts -name "*.py" -exec python {} \;

docs/source/generator_scripts/generate_animations.py

@@ -0,0 +1,64 @@
+import argparse
+import os
+
+import numpy as np
+import psyneulink as pnl
+
+parser = argparse.ArgumentParser()
+parser.add_argument(
+    "-d",
+    "--directory",
+    type=str,
+    default=os.path.join(os.path.dirname(__file__), "..", "_images"),
+    help="Path to store generated animations",
+)
+args = parser.parse_args()
+
+
+# Based on tests/composition/test_learning.py::TestLearningPathwayMethods::test_run_no_targets
+def composition_xor_animation():
+    in_to_hidden_matrix = np.random.rand(2, 10)
+    hidden_to_out_matrix = np.random.rand(10, 1)
+
+    inp = pnl.TransferMechanism(name="Input", default_variable=np.zeros(2))
+
+    hidden = pnl.TransferMechanism(
+        name="Hidden", default_variable=np.zeros(10), function=pnl.Logistic()
+    )
+
+    output = pnl.TransferMechanism(
+        name="Output", default_variable=np.zeros(1), function=pnl.Logistic()
+    )
+
+    in_to_hidden = pnl.MappingProjection(
+        name="Input Weights",
+        matrix=in_to_hidden_matrix.copy(),
+        sender=inp,
+        receiver=hidden,
+    )
+
+    hidden_to_out = pnl.MappingProjection(
+        name="Output Weights",
+        matrix=hidden_to_out_matrix.copy(),
+        sender=hidden,
+        receiver=output,
+    )
+
+    xor_comp = pnl.Composition()
+
+    xor_comp.add_backpropagation_learning_pathway(
+        [inp, in_to_hidden, hidden, hidden_to_out, output],
+        learning_rate=10,
+    )
+    xor_inputs = np.array([[0, 0], [0, 1], [1, 0], [1, 1]])
+    xor_comp.learn(
+        inputs={inp: xor_inputs},
+        animate={
+            pnl.SHOW_LEARNING: True,
+            pnl.MOVIE_DIR: args.directory,
+            pnl.MOVIE_NAME: "Composition_XOR_animation",
+        },
+    )
+
+
+composition_xor_animation()

psyneulink/core/compositions/composition.py

@@ -775,7 +775,7 @@
 
     **Composition with Learning**
 
-    .. figure:: _static/Composition_XOR_animation.gif
+    .. figure:: _images/Composition_XOR_animation.gif
        :alt: Animation of Composition with learning
        :scale: 50 %