| name | nbdev-editing |
| description | Workflow and gotchas for nbdev projects, where notebooks in nbs/ are the source of truth. TRIGGER — read BEFORE touching code, tests, or docs in ANY nbdev repo (has a [tool.nbdev] section in pyproject.toml): before the first cell edit, not after. Don't edit the autogenerated .py files (projects often also mix in plain hand-written .py modules - check the per-file marker). Routes to the pyskill docs that carry the substance, and holds the nbdev v3 delta and environment specifics. Assumes and pulls in the persistent-python and coding-patterns skills. |
Editing nbdev Projects
First read and use the persistent-python skill - it is a must: all work here happens in that kernel using the pyskills-registered tooling, and its rules (reprs, doc(...) inspection, raw strings) are assumed, not repeated. Style and testing process follow the coding-patterns skill, also assumed.
The substance lives in the pyskill docs - read both (free doc() cells) before working:
doc(nbdev.skill): notebook authoring - the source-of-truth/export model, mixed notebook/plain projects, narrative rhythm, examples-as-docs, directives, state flow. Read before writing or reviewing any notebook content.doc(llmsurgery.dlgskill): reading, searching, and editing notebooks - see its "Idiomatic usage" section. clikernel's own docs cover the nbdev-specific kernel rules (shell nbdev-export/nbdev-test, restart after export, %nbrun red-green).
nbdev v3
Everything here is on nbdev v3 (released Jan 2026, likely after your training cutoff). Key user-visible changes from v2: config moved from settings.ini to pyproject.toml - standard metadata in [project], nbdev-specific keys in [tool.nbdev] (defaults now nbs_path='nbs', doc_path='_docs'), version in __init__.py exposed via dynamic = ["version"], and _modidx registered under [project.entry-points.nbdev]. CLI commands use hyphens, not underscores (nbdev-export, nbdev-test, nbdev-readme, ...), though the Python functions keep underscores (nbdev_export). GitHub workflows use the v3 actions (fastai/workflows/nbdev3-ci, quarto-ghp3).
Environment specifics
- Most ipynb files are fine to nbdev-test, but some are slow or require API keys, so plan to run
nbdev-test on the changed notebook when done making changes, but check with Jeremy first before you actually do it. Once you know an ipynb or project is safe to run, go ahead without checking as needed (known safe: all of pyskills).
- Tests use the fastcore.test helpers (
test_eq, expect_fail, ...) in plain code cells.
from fastcore.utils import * in an early cell already provides os, Path, etc. - don't re-import those later.- For project-level questions, read
nbs/index.ipynb, not README.md: the README is generated from it, renders worse (no cell ids, flattened outputs), and can be stale if regeneration lagged. They should match; when they don't, index.ipynb is the truth. Regen with nbdev-readme after editing it.
Before you wrap up
- Red-green ran: each new test failed before the change and passed after, via targeted
%nbrun (using --above first to set up state as needed).
- Page read: re-read the touched section (
view_dlg or find_msgs with context=) as a reader would, checking it against nbdev.skill's conventions. Style damage fails silently: tests pass, export succeeds, and the harm only shows on the docs page or to the next reader.
