jellycell.export.tearsheet

Artifact filtering — tearsheet tag (opt-in)

For notebooks with many intermediate debug artifacts, mark the subset that belongs on the polished tearsheet with the tearsheet tag, either on the cell or on the artifact:

# Cell-level tag — all artifacts from this cell are included.
# %% tags=["jc.figure", "name=fig1", "tearsheet"]
jc.figure("artifacts/headline.png", caption="Main result")

# Or artifact-level — fine-grained (a cell can produce multiple
# artifacts, only some tearsheet-worthy):
jc.save(debug_dict, "artifacts/debug.json")                # excluded
jc.save(headline, "artifacts/headline.json",
        tags=["tearsheet"])                                # included

Filtering is auto-enabled when any artifact in the run carries the tearsheet tag (cell- or artifact-level). A notebook with no tagging behaves exactly as before — every renderable artifact is inlined — so the feature is strictly additive.

Default output is manuscripts/tearsheets/<stem>.md. That subfolder convention keeps auto-generated files out of the hand-authored work that lives at the root of manuscripts/ — paper drafts, decision memos, thesis chapters — which would otherwise get blown away on regenerate.

Generate a curated markdown tearsheet from a notebook + cached manifests.

A tearsheet is a curated, auto-generated view of a notebook — markdown narration, key figures, and JSON summaries laid out for reading (or printing). Unlike :func:export_md which dumps every cell with its outputs, export_tearsheet skips code source by default and only surfaces the artifacts that map cleanly to markdown (images + small JSON).

Inclusion rules:

  • Markdown cells — included verbatim.

  • Code cells with image artifacts (.png / .svg / .jpg) — inlined with relative paths so GitHub renders them in-place.

  • Code cells with JSON artifacts — top-level keys rendered as a two-column table (nested dicts flatten to a.b keys).

  • Code cells tagged kind=setup — source shown as a fenced block (hyperparams surface naturally).

  • Everything else (plain step cells, parquet artifacts, stream output, display-data blobs) is skipped.

Module Contents

Functions

export_tearsheet

Write a curated markdown tearsheet for notebook_path to output_path.

API

jellycell.export.tearsheet.export_tearsheet(notebook_path: pathlib.Path, manifests_by_cell: dict[str, jellycell.cache.manifest.Manifest], output_path: pathlib.Path, project_root: pathlib.Path) → pathlib.Path

Write a curated markdown tearsheet for notebook_path to output_path.

Args: notebook_path: Source .py notebook. manifests_by_cell: Map of {notebook_stem}:{ordinal} → :class:Manifest. output_path: Target file. Parent directories are created. project_root: Project root — used to resolve artifact paths relative to output_path’s parent.