Address review feedback

- Install requirements_docs.txt in the docs deploy workflow instead of an
  ad-hoc package list (Copilot)
- Run zensical build --clean --strict in both docs workflows to match the
  validated command and fail fast on warnings (Copilot)
- Scope contents: write permission to the deploy job with an explanatory
  comment instead of workflow-level (CodeRabbit)
- Pin peaceiris/actions-gh-pages to the v4 commit SHA for supply-chain
  safety (CodeRabbit)
- Continue past per-notebook conversion failures and exit non-zero at the
  end so one bad notebook doesn't hide the rest (CodeRabbit)

Author: giswqs

.github/workflows/docs-build.yml

@@ -33,7 +33,7 @@ jobs:
                   pip install -r requirements.txt -r requirements_dev.txt -r requirements_docs.txt
                   pip install .
             - run: python scripts/convert_notebooks.py
-            - run: zensical build
+            - run: zensical build --clean --strict
             - name: Deploy to Netlify
               uses: nwtgck/actions-netlify@v4.0
               with:

.github/workflows/docs.yml

@@ -3,11 +3,12 @@ on:
     push:
         branches:
             - main
-permissions:
-    contents: write
 jobs:
     deploy:
         runs-on: ubuntu-latest
+        # Required to push the built site to the gh-pages branch.
+        permissions:
+            contents: write
         steps:
             - uses: actions/checkout@v7
             - uses: actions/setup-python@v6
@@ -17,13 +18,12 @@ jobs:
               run: |
                   python -m pip install --upgrade pip
                   pip install --user --no-cache-dir Cython
-                  pip install --user -r requirements.txt -r requirements_dev.txt
+                  pip install --user -r requirements.txt -r requirements_dev.txt -r requirements_docs.txt
                   pip install --user .
-            - run: pip install zensical mkdocstrings-python nbconvert nbformat
             - run: python scripts/convert_notebooks.py
-            - run: zensical build
+            - run: zensical build --clean --strict
             - name: Deploy to GitHub Pages
-              uses: peaceiris/actions-gh-pages@v4
+              uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4
               with:
                   github_token: ${{ secrets.GITHUB_TOKEN }}
                   publish_dir: ./site

scripts/convert_notebooks.py

@@ -11,6 +11,7 @@
 """
 
 import pathlib
+import sys
 
 import nbformat
 from nbconvert import MarkdownExporter
@@ -46,11 +47,26 @@ def convert_notebook(nb_path: pathlib.Path) -> pathlib.Path:
 
 
 def main() -> None:
-    """Convert all notebooks in the configured docs directories."""
+    """Convert all notebooks in the configured docs directories.
+
+    Conversion continues past individual failures so that one broken
+    notebook does not hide the status of the others; the script exits
+    with a non-zero status if any notebook failed to convert.
+    """
+    failures = []
     for dir_name in NOTEBOOK_DIRS:
         for nb_path in sorted((ROOT / dir_name).glob("*.ipynb")):
-            md_path = convert_notebook(nb_path)
-            print(f"Converted {nb_path.relative_to(ROOT)} -> {md_path.name}")
+            try:
+                md_path = convert_notebook(nb_path)
+            except Exception as e:
+                failures.append(nb_path)
+                print(f"FAILED to convert {nb_path.relative_to(ROOT)}: {e}")
+            else:
+                print(f"Converted {nb_path.relative_to(ROOT)} -> {md_path.name}")
+
+    if failures:
+        print(f"{len(failures)} notebook(s) failed to convert.")
+        sys.exit(1)
 
 
 if __name__ == "__main__":