pypresent 0.1.0__py3-none-any.whl

pypresent/__init__.py

@@ -0,0 +1,76 @@
+"""pypresent - the notebook *is* the slides, and this turns it into one HTML file.
+
+A deck is declared once, in the first cell of the notebook that holds it::
+
+    from pypresent import Presentation, slide, code, result, figure
+
+    deck = Presentation(
+        slides='talk-slides.ipynb',    # this notebook: nothing but slide() calls
+        source='talk.ipynb',           # what code(), result() and figure() quote
+        output='out/talk.html',
+        title='A talk', lang='en', theme='office',
+    )
+
+and every cell after it is a slide::
+
+    slide('''
+    ## What it does
+
+    - the code on the slide is the code that ran
+    - the number on the slide is the number it printed
+    ''', code('tokenize'), result('tokenize'))
+
+``code()``, ``result()`` and ``figure()`` are read out of the source notebook at
+build time, so the listing, the number and the chart on a slide are the ones
+that actually ran, and a name that stops matching is reported rather than going
+quietly stale.
+
+Then ``pypresent build`` runs the source notebook, runs this one, says what has
+drifted, and writes one self-contained HTML file.
+
+(A plain markdown file works as a source too, cut into slides by its headings
+and ``---`` lines.  It quotes nothing, so it is the lesser half of this.)
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .blocks import MIME, SlideSpec, code, figure, image, md, notes, out, result, slide
+from .context import active
+from .deck import CONFIG_MIME, Deck, parse, parse_markdown, parse_notebook
+from .markup import inline, trim_text
+from .model import Slide
+from .presentation import Presentation
+from .render import render_deck, render_markdown, render_slide
+from .theme import Theme
+from .theme import available as available_themes
+
+__all__ = [
+    "CONFIG_MIME",
+    "MIME",
+    "Deck",
+    "Presentation",
+    "Slide",
+    "SlideSpec",
+    "Theme",
+    "__version__",
+    "active",
+    "available_themes",
+    "code",
+    "figure",
+    "image",
+    "inline",
+    "md",
+    "notes",
+    "out",
+    "parse",
+    "parse_markdown",
+    "parse_notebook",
+    "render_deck",
+    "render_markdown",
+    "render_slide",
+    "result",
+    "slide",
+    "trim_text",
+]

pypresent/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

pypresent/assets/deck.css

@@ -0,0 +1,157 @@
+/* The deck stylesheet.  Every colour, size and font is a custom property that
+   the theme sets, so restyling a deck never means editing this file.
+
+   The stage is a fixed 16:9 box letterboxed on a backdrop, and everything on it
+   is sized in cqh (1cqh = 1% of the slide's height) so the slide scales like a
+   projected slide instead of reflowing like a web page. */
+
+*,*::before,*::after{box-sizing:border-box}
+*{margin:0;padding:0}
+html,body{height:100%}
+body{
+  display:flex; align-items:center; justify-content:center;
+  background:var(--pp-backdrop); font-family:var(--pp-font); overflow:hidden;
+  -webkit-font-smoothing:antialiased;
+}
+.deck{
+  position:relative; overflow:hidden; border:1px solid var(--pp-line);
+  width:min(96vw,163.6vh); height:min(54vw,92vh);
+  background:var(--pp-canvas); container-type:size;
+  box-shadow:var(--pp-stage-shadow);
+}
+.slide{position:absolute; inset:0; display:none; flex-direction:column;
+       padding:var(--pp-pad)}
+.slide.active{display:flex}
+
+/* ---- title ---- */
+.title{font-size:var(--pp-title); line-height:1.1; font-weight:var(--pp-title-weight);
+       color:var(--pp-accent); letter-spacing:var(--pp-title-tracking)}
+.title-rule{margin-top:1.6cqh; height:var(--pp-rule); width:100%;
+  background:linear-gradient(var(--pp-rule-dir),var(--pp-accent) 0 22%,var(--pp-line) 22%)}
+
+/* ---- body ---- */
+.body{flex:1; min-height:0; margin-top:2.6cqh; overflow:hidden}
+.body.split{display:flex; gap:4cqh; align-items:flex-start}
+.body.split > .col{min-width:0; max-height:100%; overflow:hidden}
+.body.split .bullets li{max-width:none}
+.body.split pre{margin-top:0}
+.fit{transform-origin:top var(--pp-start)}
+
+p.lead{font-size:var(--pp-lead); line-height:1.3; color:var(--pp-ink);
+       margin-bottom:1.6cqh; max-width:62ch}
+p.subhead{font-size:var(--pp-subhead); line-height:1.2; color:var(--pp-accent2);
+       font-weight:700; margin:1.8cqh 0 1cqh}
+ul.bullets,ol.bullets{list-style:none; margin-bottom:1.2cqh}
+ul.bullets>li,ol.bullets>li{
+  position:relative; padding-inline-start:3.4cqh; margin-bottom:var(--pp-bullet-gap);
+  font-size:var(--pp-bullet); line-height:1.3; color:var(--pp-ink); max-width:54ch;
+}
+ul.bullets>li::before{content:var(--pp-bullet-glyph); position:absolute;
+  inset-inline-start:0; top:.05em; font-size:.55em; color:var(--pp-accent2); line-height:1.9}
+ol.bullets{counter-reset:b}
+ol.bullets>li::before{counter-increment:b; content:counter(b) "."; position:absolute;
+  inset-inline-start:0; color:var(--pp-accent2); font-weight:700; font-size:.8em; top:.15em}
+ul.bullets.sub{margin:.9cqh 0 .4cqh}
+ul.bullets.sub > li{font-size:.8em; margin-bottom:1.2cqh; padding-inline-start:2.6cqh}
+ul.bullets.sub > li::before{content:var(--pp-subbullet-glyph); font-size:.9em; top:0}
+li b,li strong,p strong{font-weight:700; color:var(--pp-accent)}
+em{font-style:italic}
+a{color:var(--pp-accent2)}
+blockquote.quote{
+  margin:1.4cqh 0; padding-inline-start:1.6cqh;
+  border-inline-start:var(--pp-rule) solid var(--pp-accent2);
+  font-size:var(--pp-quote); line-height:1.28; color:var(--pp-accent);
+  font-weight:700; max-width:50ch;
+}
+
+/* ---- code and output: always left to right, because Python does not read rtl ---- */
+code{font-family:var(--pp-mono); font-size:.9em; color:var(--pp-inline-ink);
+  background:var(--pp-soft); padding:0 .3em; border-radius:.3cqh;
+  direction:ltr; display:inline-block; unicode-bidi:isolate}
+b code,strong code{color:var(--pp-accent)}
+pre{
+  direction:ltr; text-align:left; unicode-bidi:isolate; white-space:pre-wrap;
+  overflow-wrap:anywhere; tab-size:2; margin:1.2cqh 0;
+  font-family:var(--pp-mono); font-size:var(--pp-code); line-height:1.38;
+  padding:1.4cqh 1.8cqh; background:var(--pp-code-bg); color:var(--pp-code-fg);
+  border:none; border-radius:var(--pp-radius);
+}
+pre code{background:none; padding:0; font-size:1em; display:block; color:inherit}
+pre.output{background:var(--pp-out-bg); color:var(--pp-out-fg);
+  border:1px solid var(--pp-line)}
+
+/* ---- pictures ---- */
+figure.image{margin:1.4cqh auto; line-height:0; background:var(--pp-frame);
+  border:var(--pp-frame-width) solid var(--pp-frame); outline:1px solid var(--pp-line);
+  box-shadow:var(--pp-frame-shadow); width:fit-content; max-width:100%}
+figure.image img{display:block; width:100%; height:auto; max-height:var(--pp-image-max);
+  object-fit:contain}
+
+/* ---- tables ---- */
+table{border-collapse:collapse; margin:1.2cqh 0; font-size:var(--pp-table); line-height:1.25}
+th,td{border:1px solid var(--pp-line); padding:.7cqh 1.2cqh; text-align:start;
+      vertical-align:top; color:var(--pp-ink)}
+thead th{background:var(--pp-accent2); color:var(--pp-head-fg); font-weight:700;
+      border-color:var(--pp-accent2)}
+thead th code{background:rgba(255,255,255,.18); color:var(--pp-head-fg)}
+tbody tr:nth-child(even){background:var(--pp-row-alt)}
+.rawhtml{overflow:hidden}
+.rawhtml table{direction:ltr; font-family:var(--pp-mono); font-size:calc(var(--pp-table) * .85)}
+.rawhtml thead th{background:var(--pp-accent2)}
+
+/* ---- footer ---- */
+.footer{display:flex; justify-content:space-between; align-items:baseline;
+  font-size:var(--pp-footer); color:var(--pp-muted); padding-top:1.4cqh}
+.footer .num{font-variant-numeric:tabular-nums; direction:ltr}
+.slide.cover .footer{visibility:hidden}
+
+/* ---- title slide ---- */
+.slide.cover{align-items:center; justify-content:center; text-align:center}
+.slide.cover .title{font-size:var(--pp-cover-title); font-weight:var(--pp-cover-weight)}
+.slide.cover .cover-rule{width:34cqh; height:.4cqh; background:var(--pp-accent2);
+  margin:3.4cqh auto}
+.slide.cover .body{flex:0 0 auto; margin-top:0; text-align:center}
+.slide.cover .body p.lead{font-size:3.1cqh; color:var(--pp-muted); max-width:none;
+  margin-inline:auto}
+.slide.cover ol.bullets,.slide.cover ul.bullets{display:inline-block; text-align:start}
+.cover-band{position:absolute; inset-inline:0; bottom:0; height:2.4cqh;
+  background:linear-gradient(var(--pp-rule-dir),var(--pp-accent) 0 62%,var(--pp-accent2) 62%)}
+
+/* ---- chrome, on the backdrop and never on the slide ---- */
+.progress{position:fixed; top:0; inset-inline:0; height:3px; background:rgba(0,0,0,.10)}
+.progress>i{display:block; height:100%; background:var(--pp-accent)}
+.chrome{position:fixed; bottom:10px; inset-inline-end:16px; display:flex;
+  align-items:center; gap:8px; color:var(--pp-muted); font-size:12px}
+.chrome .dots{display:flex; gap:4px}
+.chrome .dots i{width:5px; height:5px; border-radius:3px; background:rgba(0,0,0,.18)}
+.chrome .dots i.on{width:14px; background:var(--pp-accent)}
+.hint{position:fixed; bottom:10px; inset-inline-start:16px; color:var(--pp-muted);
+  font-size:11px; opacity:.75}
+.notes{display:none}
+
+/* ---- motion: a fade and an appear, nothing more ---- */
+.reveal{opacity:0; transform:translateY(1.4cqh);
+  transition:opacity var(--pp-motion) ease,transform var(--pp-motion) ease}
+.slide.active .reveal{opacity:1; transform:none}
+.slide.active .title{transition-delay:.05s}
+.slide.active .title-rule{transition-delay:.15s}
+.slide.active .body{transition-delay:.25s}
+.slide li{opacity:0; transform:translateX(-1.2cqh);
+  transition:opacity .4s ease,transform .4s ease}
+[dir="rtl"] .slide li{transform:translateX(1.2cqh)}
+.slide.active li{opacity:1; transform:none}
+.slide.active li:nth-child(1){transition-delay:.30s}
+.slide.active li:nth-child(2){transition-delay:.45s}
+.slide.active li:nth-child(3){transition-delay:.60s}
+.slide.active li:nth-child(4){transition-delay:.75s}
+.slide.active li:nth-child(5){transition-delay:.90s}
+@media (prefers-reduced-motion:reduce){.reveal,.slide li{transition:none}}
+
+@media print{
+  body{display:block; background:#fff; overflow:visible}
+  .deck{width:100%; height:100vh; box-shadow:none}
+  .slide{position:static; display:flex !important; page-break-after:always; height:100vh}
+  .fit{transform:none !important}
+  .reveal,.slide li{opacity:1 !important; transform:none !important}
+  .progress,.chrome,.hint{display:none}
+}

pypresent/assets/deck.js

@@ -0,0 +1,69 @@
+const slides = [...document.querySelectorAll('.slide')];
+const rtl = document.documentElement.dir === 'rtl';
+const bar = document.querySelector('.progress > i');
+const counter = document.querySelector('.chrome .num');
+const dots = document.querySelector('.chrome .dots');
+let idx = 0;
+
+slides.forEach((_, i) => dots.insertAdjacentHTML('beforeend', `<i data-i="${i}"></i>`));
+
+// each column is measured on its own - otherwise the taller one drags the
+// shorter one down with it and both end up smaller than they need to be
+function fit(slide) {
+  const body = slide.querySelector('.body');
+  if (!body) return;
+  const avail = body.clientHeight;
+  slide.querySelectorAll('.fit').forEach(box => {
+    box.style.transform = 'none';
+    const need = Math.max(box.scrollHeight, box.getBoundingClientRect().height);
+    box.style.transform = need > avail + 1 ? `scale(${Math.max(avail / need, 0.45)})` : 'none';
+    box.dataset.scale = need > avail + 1 ? (avail / need).toFixed(3) : '1';
+  });
+}
+
+// the slide is measured again after layout, fonts and the entry build settle
+function refit() {
+  fit(slides[idx]);
+  requestAnimationFrame(() => fit(slides[idx]));
+  [120, 400, 900].forEach(t => setTimeout(() => fit(slides[idx]), t));
+}
+
+function show(n) {
+  idx = Math.max(0, Math.min(slides.length - 1, n));
+  slides.forEach((s, i) => s.classList.toggle('active', i === idx));
+  refit();
+  bar.style.width = ((idx + 1) / slides.length * 100) + '%';
+  counter.textContent = (idx + 1) + ' / ' + slides.length;
+  [...dots.children].forEach((d, i) => d.classList.toggle('on', i === idx));
+  if (location.hash !== '#' + (idx + 1)) history.replaceState(null, '', '#' + (idx + 1));
+}
+
+const next = () => show(idx + 1);
+const prev = () => show(idx - 1);
+
+addEventListener('keydown', e => {
+  const fwd = rtl ? 'ArrowLeft' : 'ArrowRight';
+  const back = rtl ? 'ArrowRight' : 'ArrowLeft';
+  if (e.key === fwd || e.key === 'PageDown' || e.key === ' ' || e.key === 'ArrowDown') { next(); e.preventDefault(); }
+  else if (e.key === back || e.key === 'PageUp' || e.key === 'ArrowUp') { prev(); e.preventDefault(); }
+  else if (e.key === 'Home') show(0);
+  else if (e.key === 'End') show(slides.length - 1);
+  else if (e.key === 'f' || e.key === 'F') document.documentElement.requestFullscreen?.();
+});
+dots.addEventListener('click', e => { if (e.target.dataset.i) show(+e.target.dataset.i); });
+
+let touch = null;
+addEventListener('touchstart', e => touch = e.changedTouches[0].clientX, {passive: true});
+addEventListener('touchend', e => {
+  if (touch === null) return;
+  const dx = e.changedTouches[0].clientX - touch;
+  if (Math.abs(dx) > 50) (dx < 0) === !rtl ? next() : prev();
+  touch = null;
+}, {passive: true});
+
+addEventListener('resize', () => fit(slides[idx]));
+addEventListener('load', () => fit(slides[idx]));
+document.fonts?.ready.then(() => fit(slides[idx]));
+document.querySelectorAll('img').forEach(im => im.complete || (im.onload = () => fit(slides[idx])));
+addEventListener('hashchange', () => show((parseInt(location.hash.slice(1)) || 1) - 1));
+show((parseInt(location.hash.slice(1)) || 1) - 1);

pypresent/blocks.py

@@ -0,0 +1,192 @@
+"""What a slide notebook writes: ``slide()`` and the blocks that go inside it.
+
+A block is a plain dict, so a slide survives the round trip through a notebook
+cell output as JSON and the deck can be rendered later with no kernel at all.
+
+Three of them - :func:`code`, :func:`result` and :func:`figure` - do not hold
+content but a reference to a cell of the *source* notebook, found by the
+``# slide: name`` comment that cell carries.  Nothing is ever pasted twice, and
+a reference that stops matching is reported by the build rather than going
+quietly stale.
+"""
+
+from __future__ import annotations
+
+from . import nbio
+from .context import active
+from .markup import clean
+
+#: A slide, carried in a cell output.
+MIME = "application/x-slide+json"
+
+LAYOUTS = ("stack", "split")
+
+
+# --------------------------------------------------------------------------
+# blocks that hold their own content
+# --------------------------------------------------------------------------
+
+def md(text: str) -> dict:
+    """A prose block.  A bare string in a ``slide()`` call means this."""
+    return {"kind": "md", "text": clean(text)}
+
+
+def out(text: str, trim: dict | None = None) -> dict:
+    """A result to show.  ``trim={'width': …, 'head': …, 'tail': …}``."""
+    return {"kind": "out", "text": clean(text), "trim": trim or {}}
+
+
+def image(path: str) -> dict:
+    """A picture, by path relative to the deck's base directory."""
+    return {"kind": "image", "path": path}
+
+
+def notes(text: str) -> dict:
+    """Speaker notes: kept in the deck, never shown on the slide."""
+    return {"kind": "notes", "text": clean(text)}
+
+
+# --------------------------------------------------------------------------
+# blocks quoted from the source notebook
+# --------------------------------------------------------------------------
+
+def code(name: str, keep=(), drop=(), trim=(), lang: str = "python") -> dict:
+    """The listing from the source cell named `name`.
+
+    The source names the cell with a ``# slide: name`` comment and says nothing
+    else about the deck; `trim` says which of its lines the room does not need
+    to read, by what they contain - ``trim=['GENRES =', ('# balance', 'seen +=
+    1')]`` - and `keep` / `drop` are line substrings for the rare case that is
+    not enough.
+    """
+    lecture = active().lecture
+    if lecture is None:
+        return {"kind": "code", "text": f"# no source to quote {name!r} from",
+                "lang": lang, "error": "this presentation declares no source notebook"}
+    cell, guessed = nbio.find_cell(lecture, name)
+    if cell is None:
+        return {"kind": "code", "text": f"# no source cell named {name!r}",
+                "lang": lang, "error": f"no source cell named {name!r}"}
+    text, error = nbio.cut(nbio.source(cell), trim)
+    block = {"kind": "code", "text": nbio.pick(text, keep, drop), "lang": lang}
+    if guessed:
+        error = f"{name!r} matched a line, not a `# slide:` name"
+    if error:
+        block["error"] = error
+    return block
+
+
+def result(name: str, keep=(), drop=(), trim: dict | None = None) -> dict:
+    """What that same named source cell printed - so a number on a slide is real."""
+    lecture = active().lecture
+    if lecture is None:
+        return {"kind": "out", "text": f"?? {name}", "trim": {},
+                "error": "this presentation declares no source notebook"}
+    cell, guessed = nbio.find_cell(lecture, name)
+    if cell is None:
+        return {"kind": "out", "text": f"?? {name}", "trim": {},
+                "error": f"no source cell named {name!r}"}
+    block = out(nbio.pick(nbio.printed(cell), keep, drop), trim)
+    if guessed:
+        block["error"] = f"{name!r} matched a line, not a `# slide:` name"
+    return block
+
+
+def figure(name: str, which: int = 0) -> dict:
+    """The picture that same named source cell drew.
+
+    A plot is code output the way a printed number is, so it is quoted by name
+    rather than saved next to the deck as a picture of its own: re-run the
+    source and the slide shows the new chart, with nothing to update by hand and
+    no file to go stale.  `which` picks among several figures.
+
+    Only the name is stored; the image itself is read out of the source notebook
+    at render time, so neither notebook carries a second copy of the bytes.
+    """
+    block = {"kind": "figure", "name": name, "which": which}
+    lecture = active().lecture
+    if lecture is None:
+        block["error"] = "this presentation declares no source notebook"
+        return block
+    cell, guessed = nbio.find_cell(lecture, name)
+    if cell is None:
+        block["error"] = f"no source cell named {name!r}"
+    elif not nbio.figures(cell):
+        block["error"] = f"the source cell {name!r} drew no figure"
+    elif guessed:
+        block["error"] = f"{name!r} matched a line, not a `# slide:` name"
+    return block
+
+
+# --------------------------------------------------------------------------
+# the slide
+# --------------------------------------------------------------------------
+
+def _as_block(item) -> dict:
+    if isinstance(item, str):
+        return md(item)
+    if isinstance(item, dict) and "kind" in item:
+        return item
+    if isinstance(item, dict):                      # {"he": …, "en": …}
+        return {"kind": "md", **{k: clean(v) for k, v in item.items()}}
+    raise TypeError(f"a slide block is a string or a block(), not {type(item).__name__}")
+
+
+class SlideSpec:
+    """What a cell returns: a slide, described.
+
+    Jupyter shows it as Markdown, so the cell reads like the slide it makes; the
+    deck reads the JSON beside it.
+    """
+
+    def __init__(self, *blocks, title: str = "", layout: str = "stack",
+                 split: tuple[int, int] = (46, 54), notes: str = "") -> None:
+        if layout not in LAYOUTS:
+            raise ValueError(f"layout must be one of {LAYOUTS}, not {layout!r}")
+        self.blocks = [_as_block(b) for b in blocks if b is not None]
+        self.title = title
+        self.layout = layout
+        self.split = list(split)
+        self.notes = clean(notes)
+
+    def payload(self) -> dict:
+        return {"blocks": self.blocks, "title": self.title,
+                "layout": self.layout, "split": self.split, "notes": self.notes}
+
+    @property
+    def errors(self) -> list[str]:
+        """Every reference on this slide that stopped matching."""
+        return [b["error"] for b in self.blocks if b.get("error")]
+
+    def as_markdown(self, lang: str = "en") -> str:
+        parts = []
+        for b in self.blocks:
+            kind = b["kind"]
+            if kind == "md":
+                parts.append(b.get(lang) or b.get("text") or next(
+                    (v for k, v in b.items() if k != "kind" and isinstance(v, str)), ""))
+            elif kind == "code":
+                parts.append(f"```{b.get('lang', '')}\n{b['text']}\n```")
+            elif kind == "out":
+                parts.append(f"```\n{b['text']}\n```")
+            elif kind == "image":
+                parts.append(f"![]({b['path']})")
+            elif kind == "figure":
+                parts.append(f"*(figure: {b['name']}, drawn by the source notebook)*")
+        return "\n\n".join(p for p in parts if p)
+
+    def _repr_mimebundle_(self, include=None, exclude=None) -> dict:
+        return {"text/markdown": self.as_markdown(), MIME: self.payload()}
+
+    def __repr__(self) -> str:
+        return self.as_markdown()
+
+
+def slide(*blocks, **kw) -> SlideSpec:
+    """Declare the slide this cell is."""
+    return SlideSpec(*blocks, **kw)
+
+
+def slide_payload(cell: dict) -> dict | None:
+    """The slide a cell declares, read back out of its stored outputs."""
+    return nbio.payload(cell, MIME)

pypresent/cli.py

@@ -0,0 +1,175 @@
+"""The `pypresent` command.
+
+The deck declares itself, so a command names an action and, at most, the file to
+act on.  A flag always wins over what the declaration says.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .presentation import Presentation
+from .theme import Theme, available
+
+SOURCES = ("*-slides.ipynb", "*.slides.md", "*-slides.md")
+
+
+def find_deck(where: Path | None = None) -> Path | None:
+    """The deck to act on when the command line names none.
+
+    Exactly one slide file in the folder is unambiguous; more than one is not,
+    and saying so beats picking one.
+    """
+    where = where or Path.cwd()
+    found = sorted({p for pattern in SOURCES for p in where.glob(pattern)})
+    if len(found) == 1:
+        return found[0]
+    if not found:
+        print(f"no slide file in {where} - name the one you mean "
+              f"(looked for {', '.join(SOURCES)})", file=sys.stderr)
+    else:
+        print(f"{len(found)} slide files in {where} - name the one you mean: "
+              + ", ".join(f.name for f in found), file=sys.stderr)
+    return None
+
+
+def load(args) -> Presentation | None:
+    named = getattr(args, "deck", None)
+    path = Path(named) if named else find_deck()
+    if path is None:
+        return None
+    if not path.exists():
+        print(f"no such file: {path}", file=sys.stderr)
+        return None
+    # a path typed at a shell means what the shell means by it; inside the deck
+    # a relative path is relative to the deck, which is a different thing
+    output = getattr(args, "output", None)
+    return Presentation.from_notebook(
+        path,
+        lang=getattr(args, "lang", None),
+        direction=getattr(args, "direction", None),
+        title=getattr(args, "title", None),
+        date=getattr(args, "date", None),
+        output=output.resolve() if output else None,
+        theme=getattr(args, "theme", None),
+        split_level=getattr(args, "split_level", None),
+        # only the flag being present is an instruction; its absence is not
+        images=False if getattr(args, "no_images", False) else None,
+    )
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="pypresent",
+        description="Slides from a Jupyter notebook, as one self-contained HTML file.")
+    p.add_argument("--version", action="version", version=f"pypresent {__version__}")
+    sub = p.add_subparsers(dest="command")
+
+    def common(parser):
+        parser.add_argument("deck", nargs="?", default=None,
+                            help="the slide notebook or markdown file "
+                                 "(default: the only one here)")
+        parser.add_argument("--lang", default=None, help="e.g. en, he")
+        parser.add_argument("--dir", dest="direction", choices=["ltr", "rtl"], default=None)
+        parser.add_argument("--theme", default=None,
+                            help=f"a built-in ({', '.join(available())}) or a theme file")
+        parser.add_argument("--title", default=None)
+        parser.add_argument("--date", default=None)
+        parser.add_argument("--split-level", type=int, default=None,
+                            help="markdown headings up to this level start a slide")
+        parser.add_argument("--no-images", action="store_true",
+                            help="leave pictures out")
+        parser.add_argument("-o", "--output", type=Path, default=None)
+        return parser
+
+    # A full build runs the source notebook and then the slide notebook, in that
+    # order, so what the deck quotes is what the source last printed.  Both flags
+    # take a run away; neither adds one.
+    b = common(sub.add_parser(
+        "build", help="run both notebooks, check the deck, render it"))
+    b.add_argument("--skip-source-run", action="store_true",
+                   help="do not run the source notebook; quote what it last printed")
+    b.add_argument("--skip-slides-run", action="store_true",
+                   help="do not run the slide notebook; check and render what is stored")
+    b.add_argument("-f", "--format", dest="fmt", choices=["html", "md"], default="html")
+
+    r = common(sub.add_parser("render", help="render the stored outputs, without executing"))
+    r.add_argument("-f", "--format", dest="fmt", choices=["html", "md"], default="html")
+
+    common(sub.add_parser("check", help="what has drifted, said and not corrected"))
+
+    # two flags, not four command names: what to write, and how to write it
+    e = common(sub.add_parser("export", help="the deck or the source notebook, as html or md"))
+    e.add_argument("-m", "--mode", choices=["slide", "nb"], default="slide",
+                   help="the deck the slide file declares, or the source notebook "
+                        "straight through nbconvert (default: slide)")
+    e.add_argument("-f", "--format", dest="fmt", choices=["html", "md"], default="html")
+    e.add_argument("--code", dest="code", action="store_true", default=None,
+                   help="nbconvert: keep the source cells (the default for html)")
+    e.add_argument("--no-code", dest="code", action="store_false",
+                   help="nbconvert: outputs only (the default for md)")
+    e.add_argument("--skip-source-run", action="store_true",
+                   help="slide+html: do not run the source notebook")
+    e.add_argument("--skip-slides-run", action="store_true",
+                   help="slide+html: do not run the slide notebook")
+    e.add_argument("--also", nargs="*", default=[], metavar="NOTEBOOK",
+                   help="further notebooks to convert beside the one chosen")
+
+    t = sub.add_parser("themes", help="the built-in themes, and what is in one")
+    t.add_argument("name", nargs="?", default=None,
+                   help="print this theme as a file you can edit and pass to --theme")
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = parser()
+    args = p.parse_args(argv)
+    if args.command is None:                   # a bare run builds the deck here
+        args = p.parse_args(["build"])
+
+    if args.command == "themes":
+        if args.name:
+            try:
+                print(Theme.resolve(args.name).to_toml(), end="")
+            except KeyError as why:
+                print(why.args[0], file=sys.stderr)
+                return 1
+            return 0
+        for name in available():
+            theme = Theme.named(name)
+            print(f"{name:<8} {theme.accent}  {(theme.css and 'custom css') or ''}".rstrip())
+        return 0
+
+    deck = load(args)
+    if deck is None:
+        return 1
+
+    if args.command == "export":
+        if args.mode == "slide":
+            if args.fmt == "html":
+                return deck.build(run_source=not args.skip_source_run,
+                                  run_slides=not args.skip_slides_run)
+            return deck.render("md")
+        if deck.source is None:
+            print("this presentation declares no source notebook", file=sys.stderr)
+            return 1
+        return deck.convert([deck.source] + [deck._at(n) for n in args.also],
+                            args.fmt, code=args.code)
+    if args.command == "build":
+        return deck.build(run_source=not args.skip_source_run,
+                          run_slides=not args.skip_slides_run, fmt=args.fmt)
+    if args.command == "render":
+        return deck.render(args.fmt)
+    if args.command == "check":
+        said = deck.check()
+        print(f"{said} thing(s) to look at" if said else "nothing to report")
+        return 1 if said else 0
+    return deck.render()
+
+
+if __name__ == "__main__":                     # pragma: no cover
+    raise SystemExit(main())