Function exec_single

docs/cli.py:411–441

Execute ONE notebook directly (no cache, no pool) and show its error immediately. The debug loop: run one → read the traceback → fix the .md → run again. On success, add it to the cache so a later build reuses it.

(page)

def exec_single(page):
    """Execute ONE notebook directly (no cache, no pool) and show its error
    immediately. The debug loop: run one → read the traceback → fix the .md →
    run again. On success, add it to the cache so a later build reuses it."""
    name = page.removesuffix(".ipynb").removesuffix(".md")
    md = f"{name}.md" if name.startswith("source/") else f"source/{name}.md"
    if not Path(md).exists():
        print(f"❌ source not found: {md}")
        sys.exit(2)
    nb = Path(md).with_suffix(".ipynb")

    # Compile + normalize the kernel so execution doesn't trip on NoSuchKernel.
    run_command(["python", "-m", "jupytext", "--to", "notebook", md])
    import nbformat
    n = nbformat.read(nb, 4)
    n.metadata["kernelspec"] = {"name": "python3", "display_name": "Python 3"}
    nbformat.write(n, nb)

    # Execute directly — a cell error prints its FULL traceback to the console.
    print(f"\n⚡ Executing {nb} (timeout {EXEC_TIMEOUT}s/cell)...\n")
    result = run_command([
        "python", "-m", "jupyter", "nbconvert", "--to", "notebook", "--execute",
        "--inplace", f"--ExecutePreprocessor.timeout={EXEC_TIMEOUT}", str(nb),
    ], check=False)

    if result.returncode == 0:
        print(f"\n✅ {nb} executed cleanly")
        jcache(["cache", "add", str(nb)], check=False)  # feed the build cache
    else:
        print(f"\n❌ {nb} failed — full traceback above. Fix {md} and re-run.")
    sys.exit(result.returncode)


def _summarize_render(warnfile: Path, renderlog: Path, returncode: int) -> int: