Merge pull request #497 from neuromatch/jupyter-book-2

Jupyter book 2

Author: iamzoltan

.github/workflows/publish-book-v2.yml

@@ -93,6 +93,9 @@ jobs:
         env:
           BASE_URL: ${{ env.BASE_URL }}
 
+      - name: Strip error output divs from built HTML
+        run: python parse_html_for_errors_v2.py student
+
       - name: Copy CNAME for custom domain
         run: cp CNAME book/_build/html/CNAME
 

generate_book_v2.py

@@ -235,28 +235,34 @@ def pre_process_notebook(file_path):
     content = open_in_colab_new_tab(content)
     content = change_video_widths(content)
     content = link_hidden_cells(content)
-    content = tag_stub_cells(content)
+    if ARG == "student":
+        content = tag_cells_allow_errors(content)
     with open(file_path, "w", encoding="utf-8") as fh:
         json.dump(content, fh, indent=1, ensure_ascii=False)
 
 
-def tag_stub_cells(content):
-    """Add skip-execution tag to cells containing raise NotImplementedError.
+def tag_cells_allow_errors(content):
+    """Add raises-exception tag to every code cell.
 
-    JB1 used allow_errors:true to silently swallow errors from these stub cells.
-    JB2 has no global equivalent, so we skip execution instead — the source is
-    still rendered (students see the stub), but no error traceback is produced.
+    JB1 used allow_errors:true globally so execution continued past any error
+    (NotImplementedError stubs, downstream NameErrors, etc.) and error output
+    divs were stripped from the HTML by parse_html_for_errors.py.
+
+    JB2 has no global allow_errors equivalent, but raises-exception on a cell
+    tells MyST to continue executing subsequent cells after an error. We apply
+    it to all code cells so that the behaviour matches JB1 exactly. A companion
+    post-processing script (parse_html_for_errors_v2.py) then strips the error
+    output divs from the built HTML before deployment.
     """
     for cell in content["cells"]:
         if cell["cell_type"] != "code":
             continue
-        if any("NotImplementedError" in s for s in cell.get("source", [])):
-            if "metadata" not in cell:
-                cell["metadata"] = {}
-            if "tags" not in cell["metadata"]:
-                cell["metadata"]["tags"] = []
-            if "skip-execution" not in cell["metadata"]["tags"]:
-                cell["metadata"]["tags"].append("skip-execution")
+        if "metadata" not in cell:
+            cell["metadata"] = {}
+        if "tags" not in cell["metadata"]:
+            cell["metadata"]["tags"] = []
+        if "raises-exception" not in cell["metadata"]["tags"]:
+            cell["metadata"]["tags"].append("raises-exception")
     return content
 
 

parse_html_for_errors_v2.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""
+Post-process JB2-built HTML to strip error output divs.
+
+JB1 equivalent: nmaci/scripts/parse_html_for_errors.py
+JB2 difference: MyST uses different CSS classes for cell output containers.
+
+JB1 class:  "cell_output docutils container"
+JB2 classes tried (in order):
+  - "cell_output"           (MyST book-theme)
+  - "output"                (fallback)
+  - any <div> containing the error text (last resort)
+
+Run as: python parse_html_for_errors_v2.py student
+"""
+
+import os
+import sys
+import yaml
+from bs4 import BeautifulSoup
+
+ARG = sys.argv[1]  # "student" or "instructor"
+
+ERROR_STRINGS = ["NotImplementedError", "NameError"]
+
+
+def main():
+    with open("tutorials/materials.yml") as fh:
+        materials = yaml.load(fh, Loader=yaml.FullLoader)
+
+    html_directory = "book/_build/html/"
+    total_removed = 0
+
+    for m in materials:
+        name = f"{m['day']}_{''.join(m['name'].split())}"
+
+        notebook_paths = []
+        if os.path.exists(f"tutorials/{name}/{m['day']}_Intro.ipynb"):
+            notebook_paths.append(
+                f"{html_directory}/tutorials/{name}/{ARG}/{m['day']}_Intro.html"
+            )
+        notebook_paths += [
+            f"{html_directory}/tutorials/{name}/{ARG}/{m['day']}_Tutorial{i + 1}.html"
+            for i in range(m["tutorials"])
+        ]
+        if os.path.exists(f"tutorials/{name}/{m['day']}_Outro.ipynb"):
+            notebook_paths.append(
+                f"{html_directory}/tutorials/{name}/{ARG}/{m['day']}_Outro.html"
+            )
+
+        for html_path in notebook_paths:
+            if not os.path.exists(html_path):
+                print(f"  Warning: {html_path} not found, skipping")
+                continue
+
+            with open(html_path, encoding="utf-8") as f:
+                contents = f.read()
+
+            parsed_html = BeautifulSoup(contents, features="html.parser")
+            removed = strip_error_divs(parsed_html)
+            total_removed += removed
+
+            # Put solution figures in center (matches JB1 behaviour)
+            for img in parsed_html.find_all("img", alt=True):
+                if img["alt"] == "Solution hint":
+                    img["align"] = "center"
+                    img["class"] = "align-center"
+
+            with open(html_path, "w", encoding="utf-8") as f:
+                f.write(str(parsed_html))
+
+            if removed:
+                print(
+                    f"  Stripped {removed} error div(s) from {os.path.basename(html_path)}"
+                )
+
+    print(f"Done. Removed {total_removed} error output div(s) total.")
+
+
+def strip_error_divs(parsed_html):
+    """Remove output divs that contain NotImplementedError or NameError text.
+
+    Tries JB1's class first, then JB2/MyST class names, then a broad sweep.
+    Returns the number of divs removed.
+    """
+    removed = 0
+
+    # JB1 class (sphinx/docutils)
+    candidates = parsed_html.find_all(
+        "div", {"class": "cell_output docutils container"}
+    )
+
+    # JB2/MyST book-theme output wrapper
+    if not candidates:
+        candidates = parsed_html.find_all("div", {"class": "cell_output"})
+
+    # Broader fallback: any <div> that directly wraps an error traceback
+    if not candidates:
+        candidates = parsed_html.find_all("div", class_=lambda c: c and "output" in c)
+
+    for div in candidates:
+        if any(err in str(div) for err in ERROR_STRINGS):
+            div.decompose()
+            removed += 1
+
+    return removed
+
+
+if __name__ == "__main__":
+    main()