docs-jenner: skip notebook re-execution (~40 min → ~1 min), add opt-in -execute variant

.github/workflows/build-combined-doc.yml

@@ -3,12 +3,16 @@ name: Build Combined Doc
 on:
   workflow_dispatch:
     inputs:
+      execute_notebooks:
+        description: 'Re-execute notebooks before building the combined doc (slower, ~30 min, validates every notebook still runs against the current API). Off by default — the fast path uses the notebook outputs already committed to docs/.'
+        type: boolean
+        default: false
       allow_notebook_errors:
-        description: 'Publish the combined doc even if notebooks have execution errors (artifact may contain tracebacks).'
+        description: 'Only relevant when execute_notebooks is true. Publish the combined doc even if notebooks have execution errors (artifact may contain tracebacks).'
         type: boolean
         default: false
       nb_timeout:
-        description: 'Per-cell execution timeout in seconds. Heavy parameter-sweep cells (e.g. nb04, nb05) can exceed the Makefile default of 600. 1800 is a comfortable headroom.'
+        description: 'Only relevant when execute_notebooks is true. Per-cell execution timeout in seconds. Heavy parameter-sweep cells (e.g. nb04, nb05) can exceed the Makefile default of 600. 1800 is a comfortable headroom.'
         type: string
         default: '1800'
 
@@ -23,9 +27,17 @@ jobs:
       - name: Install dependencies
         run: make docs-install
       - name: Build combined doc
-        # Translate the workflow_dispatch boolean into the 0/1 the Makefile uses.
-        # nb_timeout is forwarded as NB_TIMEOUT (per-cell timeout, seconds).
-        run: make docs-jenner ALLOW_NB_ERRORS=${{ inputs.allow_notebook_errors && '1' || '0' }} NB_TIMEOUT=${{ inputs.nb_timeout }}
+        # Fast path (default): docs-jenner uses the notebook outputs already
+        # committed to docs/ — no re-execution, ~1 min instead of ~30.
+        # Full path (execute_notebooks=true): docs-jenner-execute re-executes
+        # every notebook, error-gates via docs-check-nbs, then builds.
+        # ALLOW_NB_ERRORS / NB_TIMEOUT only apply on the full path.
+        run: |
+          if [ "${{ inputs.execute_notebooks }}" = "true" ]; then
+            make docs-jenner-execute ALLOW_NB_ERRORS=${{ inputs.allow_notebook_errors && '1' || '0' }} NB_TIMEOUT=${{ inputs.nb_timeout }}
+          else
+            make docs-jenner
+          fi
       - name: Upload combined_mkdocs.md
         uses: actions/upload-artifact@v7.0.1
         with:

Makefile

@@ -1,15 +1,23 @@
 # laser-generic documentation pipeline.
 #
 # Lets you reproduce locally exactly what .github/workflows/build-combined-doc.yml
-# does in CI. The "all-in-one" target is `docs-jenner`, which executes every
-# notebook under docs/, builds the MkDocs site, then flattens both into a single
-# combined_mkdocs.md suitable for RAG / MCP ingestion.
+# does in CI. The "all-in-one" target is `docs-jenner`, which reads the
+# committed notebook outputs, builds the MkDocs site, and flattens both into
+# a single combined_mkdocs.md suitable for RAG / MCP ingestion. It does NOT
+# re-execute the notebooks — that's the ~30-minute step and it's not needed
+# to build the corpus, since every notebook is committed with its outputs.
+#
+# If you want to re-execute notebooks (either for validation, or because the
+# committed outputs have drifted from the current API), use `docs-jenner-execute`
+# instead — that runs the historical full pipeline (execute + error-gate + build
+# + concat). Or run `docs-check-nbs` on its own for validation without a full
+# doc build.
 
 # All recipes are single-command invocations (echo or python script), so they
 # work identically under bash, cmd.exe, and PowerShell — no SHELL override
 # needed. Multi-step logic lives in docs/*.py helpers instead of inline shell.
 
-.PHONY: help docs-install docs-build docs-executed-nbs docs-check-nbs docs-jenner clean-docs
+.PHONY: help docs-install docs-build docs-executed-nbs docs-check-nbs docs-jenner docs-jenner-execute clean-docs
 
 PYTHON           ?= python
 SITE_DIR         ?= site
@@ -27,20 +35,23 @@ help:
 	@echo "laser-generic documentation targets"
 	@echo "===================================="
 	@echo ""
-	@echo "  make docs-install        Install runtime + docs dependencies"
-	@echo "  make docs-build          Build the MkDocs HTML site  -> $(SITE_DIR)/"
-	@echo "  make docs-executed-nbs   Execute every docs/**/*.ipynb -> $(EXEC_DIR)/"
-	@echo "  make docs-check-nbs      Fail if any executed notebook contains errors"
-	@echo "  make docs-jenner       Full pipeline (execute + check + build + concat)"
-	@echo "                           Output: $(COMBINED)"
-	@echo "  make clean-docs          Remove $(SITE_DIR)/, $(EXEC_DIR)/, $(COMBINED)"
+	@echo "  make docs-install         Install runtime + docs dependencies"
+	@echo "  make docs-build           Build the MkDocs HTML site  -> $(SITE_DIR)/"
+	@echo "  make docs-executed-nbs    Execute every docs/**/*.ipynb -> $(EXEC_DIR)/  (~30 min)"
+	@echo "  make docs-check-nbs       Fail if any executed notebook contains errors"
+	@echo "  make docs-jenner          Fast pipeline: use committed notebook outputs +"
+	@echo "                            build + concat.  Output: $(COMBINED)"
+	@echo "  make docs-jenner-execute  Full pipeline: execute notebooks + check + build +"
+	@echo "                            concat.  Slower but validates notebooks still run"
+	@echo "                            against the current API.  Output: $(COMBINED)"
+	@echo "  make clean-docs           Remove $(SITE_DIR)/, $(EXEC_DIR)/, $(COMBINED)"
 	@echo ""
 	@echo "Tunable variables (override on the command line):"
 	@echo "  PYTHON=$(PYTHON)"
 	@echo "  SITE_DIR=$(SITE_DIR)"
 	@echo "  EXEC_DIR=$(EXEC_DIR)"
 	@echo "  COMBINED=$(COMBINED)"
-	@echo "  NB_TIMEOUT=$(NB_TIMEOUT)        per-cell execution timeout (seconds)"
+	@echo "  NB_TIMEOUT=$(NB_TIMEOUT)        per-cell execution timeout (seconds; docs-jenner-execute)"
 	@echo "  ALLOW_NB_ERRORS=$(ALLOW_NB_ERRORS)   set to 1 to publish combined doc even if notebooks errored"
 	@echo "  NB_EXCLUDE=$(NB_EXCLUDE)   comma-separated substrings of paths to skip during execution"
 
@@ -68,12 +79,25 @@ docs-check-nbs: docs-executed-nbs
 	@$(PYTHON) docs/check_executed_nbs.py $(EXEC_DIR) \
 	  $(if $(filter 1 true yes,$(ALLOW_NB_ERRORS)),--allow-errors,)
 
-# ── Full combined markdown pipeline ───────────────────────────────────────────
-# docs-executed-nbs is reached transitively via docs-check-nbs. docs-build is
-# independent of notebook execution (mkdocs-jupyter has execute:false and
-# reads the source .ipynb files directly), so it's safe to keep in parallel.
-docs-jenner: docs-check-nbs docs-build
-	$(PYTHON) -c "from pathlib import Path; Path('$(COMBINED)').parent.mkdir(parents=True, exist_ok=True)"
+# ── Combined markdown pipeline (fast — uses committed notebook outputs) ──────
+# The default doc-build path. Skips the ~30-minute notebook re-execution step
+# and reads each notebook's *committed* outputs directly from docs/. That's
+# sufficient for the RAG corpus: the outputs already in the .ipynb files
+# capture every code cell's result, and re-executing them just to re-embed the
+# same content in the corpus is wasted CI time. If a notebook committer
+# forgets to re-run a cell after editing it, this fast build will not detect
+# stale outputs; use `docs-check-nbs` / `docs-jenner-execute` to re-execute and
+# fail on runtime errors against the current API.
+docs-jenner: docs-build
+	$(PYTHON) docs/concat_mkdocs.py $(SITE_DIR) docs $(COMBINED)
+
+# ── Combined markdown pipeline with fresh notebook execution ─────────────────
+# The historical full path: execute every notebook, error-gate the outputs,
+# build the site, concat everything. Use when you want to validate that all
+# notebooks still run cleanly against the current laser-generic API (typical
+# for release-time builds) — the docs-check-nbs gate is what catches drift
+# between notebook code and current APIs.
+docs-jenner-execute: docs-check-nbs docs-build
 	$(PYTHON) docs/concat_mkdocs.py $(SITE_DIR) $(EXEC_DIR) $(COMBINED)
 
 # ── Clean ─────────────────────────────────────────────────────────────────────