Add notebook rendering to the docs

.github/workflows/build.yml

@@ -63,4 +63,4 @@ jobs:
       - name: Check style against standards using ruff
         run: ruff check .
       - name: Check cleanliness of notebooks
-        run: nb-clean check examples/ 
+        run: nb-clean check docs/examples/ 

.github/workflows/documentation-test.yml

@@ -23,6 +23,10 @@ jobs:
       - name: Install dependencies
         run: |
           pip install ".[doc]" 
+      - name: Set notebook execution to false (for docs testing)
+        run: |
+          pip install pyyaml
+          python __CI_convert_notebook_execute_false_mkdocs_yaml.py mkdocs.yml
       - name: Test mkdocs build
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -15,6 +15,8 @@ coverage.xml
 .tox
 
 docs/_build
+docs/examples/*.gif
+
 site
 
 # ide

__CI_convert_notebook_execute_false_mkdocs_yaml.py

@@ -0,0 +1,20 @@
+import sys
+import yaml
+
+if len(sys.argv) != 2:
+    sys.exit('Usage: python __CI_convert_notebook_execute_false_mkdocs_yaml.py OUTPUTFILE.yml')
+
+outfname = sys.argv[1]
+print(f"Setting mkdocs-jupyter execute flag to false in mkdocs.yml, writing output to {outfname}")
+
+
+with open('mkdocs.yml', 'r') as infile:
+    conf = yaml.safe_load(infile)
+
+# If plugins block contains a dict with key 'mkdocs-jupyter', set the 'execute' flag in there to false
+nb_dict_list = list(filter(lambda param: 'mkdocs-jupyter' in param, conf['plugins']))
+if len(nb_dict_list) == 1:
+    nb_dict_list[0]['mkdocs-jupyter']['execute'] = False
+
+    with open(outfname, 'w') as outfile:
+        yaml.safe_dump(conf, outfile, sort_keys=False)

docs/assets/custom.css

@@ -1,4 +1,9 @@
-
+[data-md-color-scheme="default"] {
+    --md-primary-fg-color: #0071bc;
+}
+[data-md-color-scheme="slate"] {
+    --md-primary-fg-color:  #699812;
+}
 code.highlight {
     font-size: 18px;
 }

docs/assets/mathjax.js

@@ -1,21 +1,22 @@
 window.MathJax = {
-    loader: {load: ['[tex]/ams']},
-    tex: {
-      inlineMath: [["\\(", "\\)"]],
-      displayMath: [["\\[", "\\]"]],
-      processEscapes: true,
-      processEnvironments: true,
-      packages: {'[+]': ['ams']}
-    },
-    options: {
-      ignoreHtmlClass: ".*|",
-      processHtmlClass: "arithmatex"
-    }
-  };
+  loader: {load: ['[tex]/ams']},
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true,
+    packages: {'[+]': ['ams']}
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
 
-  document$.subscribe(() => { 
-    MathJax.startup.output.clearCache()
-    MathJax.typesetClear()
-    MathJax.texReset()
-    MathJax.typesetPromise()
-  })
+document$.subscribe(() => { 
+  MathJax.startup.output.clearCache()
+  MathJax.typesetClear()
+  MathJax.texReset()
+  MathJax.typesetPromise()
+})