Skip to content

Refactor notebooks for direct Colab editing - #47

Merged
project-delphi merged 1 commit into
mainfrom
feat/issue-43-colab-notebook-normalizer
Aug 27, 2026
Merged

Refactor notebooks for direct Colab editing#47
project-delphi merged 1 commit into
mainfrom
feat/issue-43-colab-notebook-normalizer

Conversation

@Laverde97

Copy link
Copy Markdown
Collaborator

Summary

Refactors the notebook generation workflow so Colab/Gemini edits can land directly in notebooks/*.ipynb without being retyped into scripts/content.py.

Closes #43.

What changed

  • turned scripts/gen_notebooks.py into an in-place, idempotent notebook normalizer
  • regenerated only the centrally owned scaffold: header, Setup preamble, Setup code, and footer
  • preserved notebook-owned teaching body cells in place
  • stripped outputs, execution counts, and transient per-cell Colab metadata (colab, outputId, executionInfo)
  • preserved folded-solution metadata (cellView: "form", jupyter.source_hidden, and tags: ["solution", "hide-input"])
  • preserved existing valid cell IDs; missing/invalid/duplicate IDs receive stable content-derived IDs
  • moved section objectives into _variables.yml as bilingual objectives_en / objectives_es
  • reduced scripts/content.py to centrally owned Setup code only
  • updated CLAUDE.md and notebooks/README.md to document the new ownership boundary and Colab → GitHub workflow

Validation

  • baseline run on untouched notebooks produced zero .ipynb diff
  • ran the normalizer twice with no further notebook changes
  • nbformat.validate: 12/12 valid
  • verified all 12 Setup cells are unchanged from the pre-refactor versions
  • simulated a Colab/Gemini edit and verified:
    • teaching body source is preserved
    • outputs and execution counts are removed
    • transient Colab metadata is removed
    • folded-solution metadata is preserved
    • new cells receive stable IDs
  • uv run --with pyyaml,nbformat python scripts/check_links.pyAll checks passed
  • git diff --check → clean
  • git diff -- 'notebooks/*.ipynb' → empty
  • rendered successfully with repository-pinned Quarto 1.6.40

Scope

This PR changes notebook infrastructure and ownership only. It does not implement the pedagogical notebook changes planned for #44 and does not modify the teaching bodies of the tracked notebooks.

@project-delphi

Copy link
Copy Markdown
Owner

LGTM.

@project-delphi

Copy link
Copy Markdown
Owner

We can reopen if this blocks the notebooks being updated.

@project-delphi
project-delphi merged commit 3f5ca40 into main Aug 27, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Gemini's Colab edits should land without being retyped into content.py

3 participants