afterpython 0.4.1__py3-none-any.whl → 0.4.2__py3-none-any.whl

afterpython/builders/__init__.py

@@ -8,6 +8,7 @@ from afterpython.builders.index_md import (
 )
 from afterpython.builders.jupyter_notebook import build_jupyter_notebooks
 from afterpython.builders.llms_txt import build_llms_txt
+from afterpython.builders.marimo_content import build_marimo_content
 from afterpython.builders.marimo_notebook import build_marimo_readme
 from afterpython.builders.markdown import build_markdown
 from afterpython.builders.metadata import build_metadata
@@ -19,6 +20,7 @@ __all__ = (
     "build_faq_json",
     "build_jupyter_notebooks",
     "build_llms_txt",
+    "build_marimo_content",
     "build_marimo_readme",
     "build_markdown",
     "build_metadata",

afterpython/builders/jupyter_notebook.py

@@ -17,7 +17,7 @@ def _read_notebook(notebook_path: Path, content_path: Path) -> dict | None:
         Notebook dict if valid, None if invalid or error occurred
     """
     try:
-        with open(notebook_path) as f:
+        with open(notebook_path, encoding="utf-8") as f:
             notebook = json.load(f)
     except json.JSONDecodeError:
         click.echo(f"✗ Skipping {content_path} - invalid or empty JSON")
@@ -36,8 +36,11 @@ def _read_notebook(notebook_path: Path, content_path: Path) -> dict | None:
 
 def _write_notebook(notebook: dict, notebook_path: Path):
     """Write a notebook dict to file."""
-    with open(notebook_path, "w") as f:
-        json.dump(notebook, f, indent=1)
+    # match Jupyter's own formatting (unescaped unicode, trailing newline) so
+    # rewriting a committed notebook doesn't produce a noisy diff
+    with open(notebook_path, "w", encoding="utf-8") as f:
+        json.dump(notebook, f, indent=1, ensure_ascii=False)
+        f.write("\n")
 
 
 def _has_frontmatter(notebook: dict) -> bool:
@@ -243,8 +246,10 @@ def build_jupyter_notebooks():
 
         # Iterate over all .ipynb files once
         for notebook_path in path.rglob("*.ipynb"):
-            # Skip files in _build directory
-            if "_build" in notebook_path.parts:
+            # Skip MyST output and hidden tool dirs (.ipynb_checkpoints/,
+            # .virtual_documents/), which aren't content
+            rel_parts = notebook_path.relative_to(path).parts
+            if "_build" in rel_parts or any(p.startswith(".") for p in rel_parts):
                 continue
 
             # Get path relative to afterpython/
@@ -264,9 +269,20 @@ def build_jupyter_notebooks():
             # Track if notebook was modified
             modified = False
 
-            # Add molab badge if enabled
+            # Add molab badge if enabled. A notebook generated from a marimo .py
+            # isn't committed, so the badge must open the .py instead.
             if add_molab_badge and github_url:
-                _add_molab_badge_to_notebook(notebook, github_url, content_path)
+                generated_from = (
+                    notebook.get("metadata", {})
+                    .get("afterpython", {})
+                    .get("generated_from")
+                )
+                molab_path = (
+                    content_path.with_name(generated_from)
+                    if generated_from
+                    else content_path
+                )
+                _add_molab_badge_to_notebook(notebook, github_url, molab_path)
                 modified = True
 
             # Add thumbnail to frontmatter

afterpython/builders/marimo_content.py

@@ -0,0 +1,467 @@
+"""Convert marimo notebooks in content folders into Jupyter notebooks for MyST.
+
+MyST can't read marimo `.py` notebooks, so before MyST runs we export each one
+to an `.ipynb` next to it. `marimo export ipynb --sandbox --include-outputs`
+runs the notebook in its own uv environment, built from the notebook's PEP 723
+header, so the outputs are reproducible no matter where `ap build` runs.
+
+Rules
+-----
+- A content folder is either all-marimo or all-Jupyter (`.md` doesn't count).
+  Mixing raises. Generated `.ipynb` files (stamped with
+  `metadata.afterpython.generated_from`) don't count as Jupyter.
+- In a marimo folder, `*.ipynb` is added to that folder's `.gitignore`: the
+  `.py` is the only source, the `.ipynb` is a build artifact.
+- Generated notebooks get `execute: {skip: true}` frontmatter so
+  `myst build --execute` never re-runs them on the shared kernel.
+
+Flow
+----
+build_marimo_content(use_cache)                   # called by prebuild()
+  └─ for each content folder:
+       ├─ _scan_folder()            → marimo .py / hand-written .ipynb, raises on mixing
+       ├─ _remove_orphans()         → generated .ipynb whose .py is gone
+       ├─ _sync_gitignore()         → add/remove the `*.ipynb` line
+       └─ convert_marimo_notebook() → export + _postprocess() per notebook
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import click
+from ruamel.yaml import YAML
+from ruamel.yaml.error import YAMLError
+
+import afterpython as ap
+from afterpython.builders.jupyter_notebook import _add_fields_to_frontmatter
+from afterpython.builders.marimo_notebook import is_marimo_notebook
+from afterpython.const import CONTENT_TYPES
+
+GITIGNORE_MARKER = (
+    "# afterpython: .ipynb files here are generated from marimo notebooks (.py)"
+)
+# *.ipynb: generated notebooks; __marimo__/: marimo's session cache, which
+# `marimo export` writes next to each notebook
+GITIGNORE_PATTERNS = ("*.ipynb", "__marimo__/")
+# re-export taking longer than this in `ap dev` prints a "too slow" hint
+SLOW_EXPORT_SECONDS = 10
+# nbformat cell ids: 1-64 chars of [a-zA-Z0-9-_]
+_MAX_CELL_ID_LENGTH = 64
+
+
+@dataclass
+class _FolderScan:
+    marimo: list[Path] = field(default_factory=list)
+    jupyter: list[Path] = field(default_factory=list)
+    generated: list[Path] = field(default_factory=list)
+
+
+def _iter_files(content_path: Path):
+    """Content files under a folder, skipping MyST output and hidden tool dirs
+    (`.ipynb_checkpoints/`, `.virtual_documents/`), same as url_md."""
+    for path in sorted(content_path.rglob("*")):
+        rel_parts = path.relative_to(content_path).parts
+        if "_build" in rel_parts or any(p.startswith(".") for p in rel_parts):
+            continue
+        if path.is_file():
+            yield path
+
+
+def _generated_from(notebook_path: Path) -> str | None:
+    """The `.py` filename a generated notebook was exported from, else None."""
+    try:
+        notebook = json.loads(notebook_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(notebook, dict):
+        return None
+    stamp = notebook.get("metadata", {}).get("afterpython", {})
+    return stamp.get("generated_from") if isinstance(stamp, dict) else None
+
+
+def _scan_folder(content_path: Path) -> _FolderScan:
+    scan = _FolderScan()
+    for path in _iter_files(content_path):
+        if path.suffix == ".py" and is_marimo_notebook(path):
+            scan.marimo.append(path)
+        elif path.suffix == ".ipynb":
+            if _generated_from(path):
+                scan.generated.append(path)
+            else:
+                scan.jupyter.append(path)
+    return scan
+
+
+def _check_not_mixed(content_path: Path, scan: _FolderScan):
+    if not (scan.marimo and scan.jupyter):
+        return
+
+    def _names(paths: list[Path]) -> str:
+        return ", ".join(p.relative_to(content_path).as_posix() for p in paths)
+
+    example = scan.jupyter[0].relative_to(content_path)
+    raise click.ClickException(
+        f"{content_path.name}/ mixes marimo and Jupyter notebooks:\n"
+        f"    marimo:  {_names(scan.marimo)}\n"
+        f"    Jupyter: {_names(scan.jupyter)}\n"
+        "  A content folder must use one or the other. Convert the .ipynb "
+        f"(marimo convert {example} -o {example.with_suffix('.py')}) "
+        "or move it to another content folder."
+    )
+
+
+def _remove_orphans(scan: _FolderScan):
+    """Delete generated notebooks whose marimo source no longer exists."""
+    marimo = set(scan.marimo)
+    for notebook_path in scan.generated:
+        source = notebook_path.parent / (_generated_from(notebook_path) or "")
+        if source not in marimo:
+            notebook_path.unlink()
+            click.echo(f"Removed {notebook_path.name} (its marimo source is gone)")
+
+
+def _sync_gitignore(content_path: Path, has_marimo: bool):
+    """Keep `*.ipynb` (and `__marimo__/`) in the folder's .gitignore exactly
+    while it holds marimo notebooks. Only the block afterpython wrote, starting
+    at GITIGNORE_MARKER, is ever added or removed."""
+    gitignore = content_path / ".gitignore"
+    text = gitignore.read_text(encoding="utf-8") if gitignore.exists() else ""
+    lines = text.splitlines()
+    has_ours = GITIGNORE_MARKER in lines
+
+    if has_marimo and not has_ours:
+        existing = {line.strip() for line in lines}
+        missing = [p for p in GITIGNORE_PATTERNS if p not in existing]
+        if not missing:
+            return  # the user already ignores these themselves
+        block = "\n".join([GITIGNORE_MARKER, *missing]) + "\n"
+        sep = "" if not text or text.endswith("\n") else "\n"
+        gitignore.write_text(text + sep + ("\n" if text else "") + block, "utf-8")
+        click.echo(
+            click.style(
+                f"⚠ {content_path.name}/ contains marimo notebooks: "
+                f"{', '.join(missing)} added to {content_path.name}/.gitignore\n"
+                "  (.ipynb files here are generated from .py and not committed)",
+                fg="yellow",
+            )
+        )
+    elif not has_marimo and has_ours:
+        start = lines.index(GITIGNORE_MARKER)
+        end = start + 1
+        while end < len(lines) and lines[end].strip() in GITIGNORE_PATTERNS:
+            end += 1
+        kept = lines[:start] + lines[end:]
+        while kept and not kept[-1].strip():
+            kept.pop()
+        gitignore.write_text("\n".join(kept) + "\n" if kept else "", "utf-8")
+        click.echo(
+            f"{content_path.name}/ has no marimo notebooks anymore: removed "
+            f"afterpython's ignore lines from {content_path.name}/.gitignore"
+        )
+
+
+def _marimo_version() -> str:
+    if shutil.which("marimo") is None:
+        raise click.ClickException(
+            "marimo is required to build marimo notebooks in content folders, "
+            'install it with: uv add --dev "afterpython[marimo]"'
+        )
+    result = subprocess.run(
+        ["marimo", "--version"], capture_output=True, text=True, check=False
+    )
+    return result.stdout.strip()
+
+
+def _source_hash(source: Path) -> str:
+    return hashlib.sha256(source.read_bytes()).hexdigest()
+
+
+def _is_cached(source: Path, output: Path, marimo_version: str) -> bool:
+    try:
+        notebook = json.loads(output.read_text(encoding="utf-8"))
+        stamp = notebook["metadata"]["afterpython"]
+    except (OSError, ValueError, KeyError, TypeError):
+        return False
+    return (
+        stamp.get("source_hash") == _source_hash(source)
+        and stamp.get("marimo_version") == marimo_version
+    )
+
+
+def _as_lines(source: str | list[str]) -> list[str]:
+    text = source if isinstance(source, str) else "".join(source)
+    return text.splitlines(keepends=True)
+
+
+def _parse_frontmatter(cell: dict) -> dict | None:
+    """The YAML mapping if a markdown cell is a `---`-fenced frontmatter block."""
+    if cell.get("cell_type") != "markdown":
+        return None
+    text = "".join(cell.get("source", [])).strip()
+    match = re.match(r"^---\s*\n(.*?)\n---\s*(\n|$)", text, re.DOTALL)
+    if not match:
+        return None
+    try:
+        data = YAML(typ="safe").load(match.group(1))
+    except YAMLError:
+        return None
+    return data if isinstance(data, dict) and data else None
+
+
+def _check_frontmatter_first(notebook: dict, source: Path):
+    """MyST only reads frontmatter from the first cell; anywhere else it renders
+    as text (the YAML becomes a garbled page title)."""
+    for index, cell in enumerate(notebook["cells"]):
+        if index > 0 and _parse_frontmatter(cell) is not None:
+            raise click.ClickException(
+                f"{source}: the frontmatter cell (--- ... ---) must be the first "
+                "cell of the notebook, MyST ignores it anywhere else.\n"
+                "  Move that mo.md(...) cell to the top of the file."
+            )
+
+
+def _project_import_name() -> str | None:
+    from afterpython.tools.pyproject import read_pyproject
+
+    # only the name is needed, so skip read_metadata()'s full validation
+    try:
+        name = str(read_pyproject()["project"]["name"])
+    except Exception:
+        return None
+    return name.replace("-", "_").replace(".", "_").lower()
+
+
+def _check_no_errors(notebook: dict, source: Path):
+    errors = [
+        output
+        for cell in notebook["cells"]
+        for output in cell.get("outputs", [])
+        if output.get("output_type") == "error"
+    ]
+    if not errors:
+        return
+    first = errors[0]
+    message = (
+        f"{source}: {len(errors)} cell(s) raised an error while running in the "
+        f"notebook's sandbox, first one:\n"
+        f"    {first.get('ename')}: {first.get('evalue')}"
+    )
+    package = _project_import_name()
+    if (
+        package
+        and first.get("ename") == "ModuleNotFoundError"
+        and f"'{package}'" in str(first.get("evalue"))
+    ):
+        project_path = os.path.relpath(ap.paths.user_path, source.parent)
+        message += (
+            "\n  The notebook runs in its own environment, so your package must "
+            "be declared in its PEP 723 header, e.g.:\n"
+            "    # /// script\n"
+            f'    # dependencies = ["marimo", "{package}"]\n'
+            "    # [tool.uv.sources]\n"
+            f'    # {package} = {{ path = "{project_path}", editable = true }}\n'
+            "    # ///"
+        )
+    raise click.ClickException(message)
+
+
+def _cell_id_prefix(source: Path, content_path: Path) -> str:
+    rel = source.relative_to(content_path).with_suffix("").as_posix()
+    return re.sub(r"[^A-Za-z0-9_-]", "-", rel)
+
+
+def _rewrite_cell_ids(notebook: dict, prefix: str):
+    """marimo derives cell ids from cell position, so every notebook repeats the
+    same ids and MyST reports duplicate identifiers across the project."""
+    for cell in notebook["cells"]:
+        cell_id = f"{prefix}-{cell.get('id', '')}"
+        if len(cell_id) > _MAX_CELL_ID_LENGTH:
+            digest = hashlib.sha1(cell_id.encode()).hexdigest()[:8]
+            cell_id = f"{cell_id[: _MAX_CELL_ID_LENGTH - 9]}-{digest}"
+        cell["id"] = cell_id
+
+
+def _postprocess(
+    notebook: dict, source: Path, content_path: Path, marimo_version: str
+) -> dict:
+    for cell in notebook["cells"]:
+        cell["source"] = _as_lines(cell.get("source", ""))
+    _check_no_errors(notebook, source)
+    _check_frontmatter_first(notebook, source)
+    # outputs come from the sandbox, `myst build --execute` must not redo them
+    _add_fields_to_frontmatter(notebook, {"execute": "{skip: true}"})
+    _rewrite_cell_ids(notebook, _cell_id_prefix(source, content_path))
+    notebook.setdefault("metadata", {})["afterpython"] = {
+        "generated_from": source.name,
+        "source_hash": _source_hash(source),
+        "marimo_version": marimo_version,
+    }
+    return notebook
+
+
+def convert_marimo_notebook(
+    source: Path, content_path: Path, marimo_version: str, use_cache: bool = True
+) -> bool:
+    """Export one marimo notebook to `<stem>.ipynb` next to it.
+
+    Returns True if it was (re-)exported, False if the cached output was reused.
+    """
+    output = source.with_suffix(".ipynb")
+    if use_cache and _is_cached(source, output, marimo_version):
+        return False
+
+    click.echo(f"Running marimo notebook {source.relative_to(ap.paths.user_path)}...")
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_output = Path(tmp) / output.name
+        result = subprocess.run(
+            [
+                "marimo",
+                "export",
+                "ipynb",
+                str(source),
+                "-o",
+                str(tmp_output),
+                "--include-outputs",
+                "--sandbox",
+                # keep the author's cell order, not marimo's dependency order
+                "--sort",
+                "top-down",
+                "--force",
+            ],
+            check=False,
+        )
+        # marimo (>=0.25) exits 1 when a cell fails but still writes the
+        # notebook, so read it whenever it exists: _postprocess reports the
+        # actual cell error, which is far more useful than the exit code
+        if not tmp_output.exists():
+            raise click.ClickException(f"marimo export failed for {source}")
+        notebook = json.loads(tmp_output.read_text(encoding="utf-8"))
+
+    notebook = _postprocess(notebook, source, content_path, marimo_version)
+    if result.returncode != 0:
+        raise click.ClickException(f"marimo export failed for {source}")
+    output.write_text(
+        json.dumps(notebook, indent=1, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+    return True
+
+
+def _prepare_folder(content_path: Path) -> list[Path]:
+    """Folder-level rules; returns the folder's marimo notebooks."""
+    scan = _scan_folder(content_path)
+    _check_not_mixed(content_path, scan)
+    _remove_orphans(scan)
+    _sync_gitignore(content_path, has_marimo=bool(scan.marimo))
+    return scan.marimo
+
+
+def build_marimo_content(use_cache: bool = True):
+    """Convert every marimo notebook in the content folders to `.ipynb`.
+
+    Args:
+        use_cache: reuse a generated notebook when its `.py` and the marimo
+            version are unchanged. `ap build` passes False: a notebook's
+            outputs can change without its `.py` changing (e.g. it imports the
+            project's own package), so production builds always re-run.
+    """
+    marimo_version: str | None = None
+    for content_type in sorted(CONTENT_TYPES):
+        content_path = ap.paths.afterpython_path / content_type
+        if not content_path.exists():
+            continue
+        notebooks = _prepare_folder(content_path)
+        if not notebooks:
+            continue
+        marimo_version = marimo_version or _marimo_version()
+        for source in notebooks:
+            convert_marimo_notebook(source, content_path, marimo_version, use_cache)
+
+
+def remove_generated_notebooks(content_path: Path) -> int:
+    """Delete the `.ipynb` files afterpython generated in a content folder."""
+    if not content_path.exists():
+        return 0
+    generated = _scan_folder(content_path).generated
+    for notebook_path in generated:
+        notebook_path.unlink()
+    return len(generated)
+
+
+def watch_marimo_content(
+    content_types: set[str], stop_event: threading.Event, interval: float = 1.0
+):
+    """`ap dev`: re-export marimo notebooks when their `.py` is saved.
+
+    Best effort: every save re-runs the whole notebook, so errors are printed
+    instead of stopping the dev servers, and slow re-runs print a hint.
+    """
+    content_paths = [
+        ap.paths.afterpython_path / content_type
+        for content_type in sorted(content_types)
+    ]
+
+    def _snapshot() -> dict[Path, float]:
+        mtimes = {}
+        for content_path in content_paths:
+            if not content_path.exists():
+                continue
+            for path in content_path.rglob("*.py"):
+                rel_parts = path.relative_to(content_path).parts
+                if "_build" in rel_parts or any(p.startswith(".") for p in rel_parts):
+                    continue
+                try:
+                    mtimes[path] = path.stat().st_mtime
+                except OSError:
+                    continue
+        return mtimes
+
+    marimo_version: str | None = None
+    seen = _snapshot()
+    while not stop_event.wait(interval):
+        current = _snapshot()
+        changed = {path for path, mtime in current.items() if seen.get(path) != mtime}
+        removed = seen.keys() - current.keys()
+        seen = current
+        if not changed and not removed:
+            continue
+        for content_path in content_paths:
+            if not content_path.exists():
+                continue
+            if not any(p.is_relative_to(content_path) for p in changed | removed):
+                continue
+            try:
+                notebooks = _prepare_folder(content_path)
+                for source in notebooks:
+                    if source not in changed:
+                        continue
+                    marimo_version = marimo_version or _marimo_version()
+                    start = time.monotonic()
+                    convert_marimo_notebook(source, content_path, marimo_version)
+                    elapsed = time.monotonic() - start
+                    if elapsed > SLOW_EXPORT_SECONDS:
+                        rel = source.relative_to(ap.paths.afterpython_path)
+                        click.echo(
+                            click.style(
+                                f"⚠ {rel} took {elapsed:.0f}s to re-run after "
+                                "saving.\n"
+                                "  ap dev re-runs the whole notebook on every "
+                                "save. If this is too slow, finish editing it in "
+                                "`marimo edit --sandbox` first, then run ap dev.",
+                                fg="yellow",
+                            )
+                        )
+            except click.ClickException as e:
+                click.echo(click.style(f"✗ {e.format_message()}", fg="red"))
+            except Exception as e:  # keep watching: a crash here would go unnoticed
+                click.echo(click.style(f"✗ marimo re-export failed: {e!r}", fg="red"))

afterpython/builders/marimo_notebook.py

@@ -28,18 +28,19 @@ def _create_molab_url(github_url: str, content_path: Path) -> str:
 def is_marimo_notebook(path: Path) -> bool:
     """Check if a Python file is a marimo notebook.
 
-    Looks for marimo's two reliable signature lines (`__generated_with` and
-    `marimo.App(`) — both are emitted by marimo for any notebook file, and
-    a plain script that just `import`s marimo won't match.
+    Looks for `marimo.App(`, which every notebook needs and a plain script
+    that just `import`s marimo won't have. `__generated_with` isn't required:
+    marimo writes it, but hand-written notebooks (e.g. copied from the docs)
+    often lack it and marimo runs them fine.
     """
     if not path.exists() or not path.is_file():
         return False
     try:
-        # marimo's signature is at the top of the file, no need to read all
-        head = path.read_text(encoding="utf-8", errors="ignore")[:2048]
+        # whole file: a long PEP 723 header can push `marimo.App(` far down
+        text = path.read_text(encoding="utf-8", errors="ignore")
     except OSError:
         return False
-    return "__generated_with" in head and "marimo.App(" in head
+    return "marimo.App(" in text
 
 
 def _export_marimo(

afterpython/cli/commands/build.py

@@ -22,6 +22,7 @@ from afterpython.builders import (
     build_faq_json,
     build_jupyter_notebooks,
     build_llms_txt,
+    build_marimo_content,
     build_marimo_readme,
     build_markdown,
     build_metadata,
@@ -84,7 +85,7 @@ def _read_api_reference() -> bool:
     return bool(website.get("api_reference", False))
 
 
-def prebuild():
+def prebuild(dev_build: bool = False):
     def _check_initialized():
         # Check if 'ap init' has been run
         afterpython_toml = ap.paths.afterpython_path / "afterpython.toml"
@@ -141,6 +142,10 @@ def prebuild():
     build_comments_json()
     build_marimo_readme(mode=_get_readme_py_mode())
     build_markdown()
+    # before build_jupyter_notebooks() so generated notebooks get the same
+    # thumbnail/molab post-processing as hand-written ones. Production builds
+    # always re-run notebooks (outputs can change without the .py changing).
+    build_marimo_content(use_cache=dev_build)
     build_jupyter_notebooks()
 
 
@@ -173,7 +178,12 @@ def postbuild(dev_build: bool = False):
             print(f"Moved: {source} to {destination}")
 
     build_content_json()
-    delete_placeholder_index_md_files()
+    # In dev, `myst start` is still running and watches myst.yml: removing the
+    # placeholder from the TOC now would make the first real page the index,
+    # so every later rebuild lands in index.json. `ap dev` deletes the
+    # placeholders when its servers stop instead.
+    if not dev_build:
+        delete_placeholder_index_md_files()
 
     website_static = ap.paths.website_path / "static"
     website_static.mkdir(parents=True, exist_ok=True)
@@ -269,62 +279,69 @@ def build(ctx: click.Context, execute: bool):
         return
 
     paths = ctx.obj["paths"]
-    prebuild()
-
-    # Determine BASE_PATH based on website URL configuration. Computed
-    # before build_pdoc() so it can wire pdoc's logo-link back to the
-    # project website root.
-    base_path = determine_base_path()
-    if base_path:
-        click.echo(f"Using BASE_PATH: {base_path}")
-    else:
-        click.echo("Using BASE_PATH: (empty - custom domain)")
-
-    if _read_api_reference():
-        build_pdoc(base_path=base_path)
-
-    node_env: NodeEnv = find_node_env()
-
-    # myst's production build
-    for content_type in CONTENT_TYPES:
-        content_path = ap.paths.afterpython_path / content_type
-        myst_yml_path = content_path / "myst.yml"
-
-        if not content_path.exists():
-            click.echo(f"{content_path} does not exist, skip building {content_type}/")
-            continue
-
-        if not myst_yml_path.exists():
-            click.echo(
-                f"No myst.yml found in {content_path}, skip building {content_type}/"
+    # prebuild() creates placeholder index.md files and edits myst.yml TOCs;
+    # remove them even if a later step fails (e.g. a marimo notebook errors)
+    try:
+        prebuild()
+
+        # Determine BASE_PATH based on website URL configuration. Computed
+        # before build_pdoc() so it can wire pdoc's logo-link back to the
+        # project website root.
+        base_path = determine_base_path()
+        if base_path:
+            click.echo(f"Using BASE_PATH: {base_path}")
+        else:
+            click.echo("Using BASE_PATH: (empty - custom domain)")
+
+        if _read_api_reference():
+            build_pdoc(base_path=base_path)
+
+        node_env: NodeEnv = find_node_env()
+
+        # myst's production build
+        for content_type in CONTENT_TYPES:
+            content_path = ap.paths.afterpython_path / content_type
+            myst_yml_path = content_path / "myst.yml"
+
+            if not content_path.exists():
+                click.echo(
+                    f"{content_path} does not exist, skip building {content_type}/"
+                )
+                continue
+
+            if not myst_yml_path.exists():
+                click.echo(
+                    f"No myst.yml found in {content_path}, skip building {content_type}/"
+                )
+                continue
+
+            if not has_content_for_myst(content_path):
+                click.echo(f"Skipping {content_type}/ (no content files found)")
+                continue
+
+            click.echo(f"Building {content_type}/...")
+            # NOTE: needs to set BASE_URL (used by MyST) so that the project website can link to the content pages correctly at e.g. localhost:5173/doc
+            base_url = f"{base_path}/{content_type}"
+            build_env = {**node_env, "BASE_URL": base_url, "BASE_PATH": base_path}
+            result = subprocess.run(
+                [
+                    "myst",
+                    "build",
+                    "--html",
+                    *(["--execute"] if execute else []),
+                    *ctx.args,
+                ],
+                cwd=content_path,
+                env=build_env,
+                check=False,
             )
-            continue
-
-        if not has_content_for_myst(content_path):
-            click.echo(f"Skipping {content_type}/ (no content files found)")
-            continue
-
-        click.echo(f"Building {content_type}/...")
-        # NOTE: needs to set BASE_URL (used by MyST) so that the project website can link to the content pages correctly at e.g. localhost:5173/doc
-        base_url = f"{base_path}/{content_type}"
-        build_env = {**node_env, "BASE_URL": base_url, "BASE_PATH": base_path}
-        result = subprocess.run(
-            [
-                "myst",
-                "build",
-                "--html",
-                *(["--execute"] if execute else []),
-                *ctx.args,
-            ],
-            cwd=content_path,
-            env=build_env,
-            check=False,
-        )
 
-        if result.returncode != 0:
-            raise Exit(result.returncode)
+            if result.returncode != 0:
+                raise Exit(result.returncode)
 
-    postbuild(dev_build=False)
+        postbuild(dev_build=False)
+    finally:
+        delete_placeholder_index_md_files()
 
     click.echo("Building project website...")
     website_env = {**node_env, "BASE_PATH": base_path}

afterpython/cli/commands/clean.py

@@ -42,10 +42,16 @@ def clean(ctx, all: bool):
     paths = ctx.obj["paths"]
     node_env: NodeEnv = find_node_env()
 
+    from afterpython.builders.marimo_content import remove_generated_notebooks
+
     # Clean MyST builds for each content type
     for content_type in CONTENT_TYPES:
         content_path = paths.afterpython_path / content_type
 
+        # .ipynb files generated from marimo notebooks are build artifacts too
+        if removed := remove_generated_notebooks(content_path):
+            click.echo(f"  Removed {removed} generated notebook(s) in {content_type}/")
+
         # Skip if no content exists
         if not has_content_for_myst(content_path):
             click.echo(f"Skipping {content_type}/ (no content found)")

afterpython/cli/commands/dev.py

@@ -230,8 +230,20 @@ def dev(
         )
         enabled_content_types = {ct for ct, flag in content_flags.items() if flag}
 
+    stop_watching = threading.Event()
+
     try:
-        prebuild()
+        prebuild(dev_build=True)
+
+        # re-export marimo notebooks on save for the content types being served
+        if enabled_content_types:
+            from afterpython.builders.marimo_content import watch_marimo_content
+
+            threading.Thread(
+                target=watch_marimo_content,
+                args=(enabled_content_types, stop_watching),
+                daemon=True,
+            ).start()
 
         # Clear .env.development before writing new ports
         env_file = paths.website_path / ".env.development"
@@ -313,4 +325,10 @@ def dev(
         # Handle Ctrl+C during subprocess.run
         pass
     finally:
+        stop_watching.set()
         cleanup_processes()
+        # runs on shutdown: postbuild() keeps the placeholder index.md files
+        # during the session (MyST servers watch myst.yml); clean them up now
+        from afterpython.builders import delete_placeholder_index_md_files
+
+        delete_placeholder_index_md_files()

afterpython/cli/main.py

@@ -90,7 +90,9 @@ class AliasGroup(click.Group):
 @click.version_option(version=__version__)
 def afterpython_group(ctx):
     """afterpython's CLI"""
-    load_dotenv(find_dotenv())  # Load environment variables from .env file
+    # usecwd: search from the user's project, not from this file's location
+    # (with an editable install that would find afterpython's own .env)
+    load_dotenv(find_dotenv(usecwd=True))
     ctx.ensure_object(dict)
     ctx.obj["paths"] = ap.paths
 

{afterpython-0.4.1.dist-info → afterpython-0.4.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: afterpython
-Version: 0.4.1
+Version: 0.4.2
 Summary: CLI tool to streamline Python package maintenance and generate a dedicated project website
 Keywords: package-maintenance,project-website,static-site-generator,developer-tools,documentation,cli-tool,ci/cd,mystmd,semantic-release,python-packaging
 Author: Stephen Yau
@@ -54,6 +54,7 @@ Description-Content-Type: text/markdown
 [MyST]: https://mystmd.org
 [MyST Markdown]: https://mystmd.org/spec/
 [Jupyter Notebook]: https://jupyter.org
+[marimo]: https://marimo.io
 [pre-commit]: https://pre-commit.com
 [pagefind]: https://pagefind.app
 [SemVer]: https://semver.org
@@ -81,7 +82,7 @@ First-time maintainers must learn multiple tools and concepts, e.g. [MyST], [Sem
 
 
 ## Core Features
-- [x] Write content directly in [MyST Markdown] or [Jupyter Notebook]
+- [x] Write content directly in [MyST Markdown], [Jupyter Notebook] or [marimo] notebooks, with reproducible outputs for marimo
 - [x] Go from writing to **website deployment in minutes** — no need to learn any of the underlying tools
 - [x] Centralize all your content in a modern, **unified project website** — from documentation to blog posts
 - [x] Zero-config orchestration — Pre-configured modern tooling with sane defaults (see [Tech Stack](#tech-stack)), so you can start maintaining packages immediately **without learning each tool**

{afterpython-0.4.1.dist-info → afterpython-0.4.2.dist-info}/RECORD

@@ -3,27 +3,28 @@ afterpython/_io/toml.py,sha256=dvmq6n4MhlJ02u_YjfC3mOnCWatfCn_J1lugavigoJw,3410
 afterpython/_io/yaml.py,sha256=raksve_gaIFJim8lQrq-kQHkRjTloed7CT2FY0oUJSg,654
 afterpython/_paths.py,sha256=FTwQ7necKYuRosCyMZPfv1eqaEmGIsyqd3yXpm-WQTA,1584
 afterpython/_typing.py,sha256=kDO25BbJCdNNkqoP9-JYC1zsOuNvzhqvSOCcam3yuAk,128
-afterpython/builders/__init__.py,sha256=2ee-FggKVZmjDazH5dLOe7irTOkHNZhQK9SK7EX_dEA,1069
+afterpython/builders/__init__.py,sha256=A8LWY4ESeH3SuhkjRcwrCgIAAZXnwHk4asNGGTmVQ9g,1166
 afterpython/builders/build_pdoc.py,sha256=lFWQzw4w_-O1PdWHst3eAbgZKkZuQXWtMBFOmZK5BlQ,2442
 afterpython/builders/comments_json.py,sha256=7gY1wy78wqSscTIFlDhwDKNYN6ioLzpDpACLBmwB9rw,3603
 afterpython/builders/content_json.py,sha256=yem8qhVjy5-aTnmUIING5ttNZFsuTQ-r5M_dYKGRyTk,5362
 afterpython/builders/faq_json.py,sha256=mMfFepRBL_1QYO0tQ6orf5ESo2LVntk55nfFzencViM,1193
 afterpython/builders/index_md.py,sha256=ZpBA1FIHgw9MXD8kRaq2OBaEAKnf94_sJmB2cG68iag,6021
-afterpython/builders/jupyter_notebook.py,sha256=9rCOrHWYbPmLllRcp5v9p2odasqQxFZN280oK8yFFd8,9693
+afterpython/builders/jupyter_notebook.py,sha256=6PBz-jYPRMhk_1MsM8pfoyVbbvCKqSr1FIp7n8xQO8g,10580
 afterpython/builders/llms_txt.py,sha256=9x-B1i1buTDJt4zGs8nugyto_pI5QIp7WUBcv-zpcso,9226
-afterpython/builders/marimo_notebook.py,sha256=hbrR4mZrNcdCVwkI2VGk-YedTsw_3wd2DWN1GMnGXG0,6337
+afterpython/builders/marimo_content.py,sha256=uqlN96eOLYgkRmPiPqcDbaWVYwB2hBV1qVWXTbbus-U,18324
+afterpython/builders/marimo_notebook.py,sha256=bYX65k8aKDVw3hdDI_EZQ1AXsd34q-M5YYwJchRANms,6362
 afterpython/builders/markdown.py,sha256=0ExfRqvOTWsgUkAVaGGNkiNDtNedRr7JR1yTGxpbsmA,8736
 afterpython/builders/metadata.py,sha256=EueKoYWM__Hb9MwX0KYejxJvouoaAxD1oz9AP-Na-ZI,3830
 afterpython/builders/url_md.py,sha256=MfXSy0f44J72OlHASir-Xscqq1onA10vtqUO_L4b1xM,3949
 afterpython/cli/__init__.py,sha256=G4AB-rllhmr7tURFc5cXJfkjZZ2bXtMBg3oy4zUGEFw,84
 afterpython/cli/commands/add.py,sha256=Ppp4msdvOwN9_-fdG5-b0-IV9p0Eef9CiIEU3srUjYk,1792
-afterpython/cli/commands/build.py,sha256=7LgNZnT0daUB7oSIR-ZziZ_pMc9YPulgsCHGkAeMqEw,11861
+afterpython/cli/commands/build.py,sha256=PhhykRYpF9Vekv8KkLnTVZ95lsL0xG61KG0OpFMwhMg,12931
 afterpython/cli/commands/bump.py,sha256=ULrZmQuQ-oJSYXNyEyCg3VxrHDhzwOSMv37Uk1fQlgs,13354
 afterpython/cli/commands/changelog.py,sha256=R4GdvJlnfd8joVnRRon9y-eM8RfSIxE1GCOspMrxXEw,1597
 afterpython/cli/commands/check.py,sha256=QBt_KHlD72QJmBordcsoGKvyX4Iuj7ezjFStuNZVaOk,1694
-afterpython/cli/commands/clean.py,sha256=havP43ZC1AKFzvscsRMF_to6TvOwruxGA5qzr6dMHvg,2529
+afterpython/cli/commands/clean.py,sha256=3KETi9-LdRdfyxwoMr59bXNaFw2NajfZIWIyu31U8JE,2841
 afterpython/cli/commands/commit_msg.py,sha256=2PYTqsxMeYaGwQSb2MER3a73gmUoSAietuApJW0XKw4,4513
-afterpython/cli/commands/dev.py,sha256=bbugeF52iQI8xr2h59yRdV-IUxM3RD4d-RqVCdj3JA0,10197
+afterpython/cli/commands/dev.py,sha256=ZOxTM_ztRM3qvoWRFBmHDKPbNiFGhdUIP1dfBFQcy1o,10937
 afterpython/cli/commands/format.py,sha256=VFwCG9KDTF6j4Y_Ewp4_RpS8uNBQNOAj9HU_G97my5A,710
 afterpython/cli/commands/init.py,sha256=1tECOi_okfuZLgbXnVHek2-7qwLDXbLLEUrnX8EPrU4,14504
 afterpython/cli/commands/init_branch_rules.py,sha256=fzAm8D5qbW3u4bEMpqPuRgO-0akuCGG7pu09JlKhYn4,243
@@ -38,7 +39,7 @@ afterpython/cli/commands/serve.py,sha256=L0LIhMGByQA_mNTOAGHQTQ8TcBfi5sgmO1_iGI2
 afterpython/cli/commands/start.py,sha256=edbPWsgr4m5P4w-0z12ObwkdD60HGzV5jFQlbwlbyyQ,4119
 afterpython/cli/commands/sync.py,sha256=Rx_Wmf8toys3FjENtcKVCw22ejEvOzyuqblWKA04dl0,6467
 afterpython/cli/commands/update.py,sha256=q_ZxbPC-4fyUPlX3Ohoz5f3cJrz5j3d5-1AH453_VTQ,9649
-afterpython/cli/main.py,sha256=XgmBo1rDv4EsX97fCfjd7kxFEu7SWNOJiiQulbzMljw,5007
+afterpython/cli/main.py,sha256=MYv7NthSmRyr5AQfOBrXjng0QB3Zem6jLlSgjXi1o9I,5121
 afterpython/const.py,sha256=R4G-rq_1sZ35aQR0eXxpNgIjbk2Aw5lvhMSKNNjiyA4,225
 afterpython/main.py,sha256=w0z6mTib3u4p2HxMrk-tIJlZtur7uRaqsbE0ewlYlSs,490
 afterpython/pcu.py,sha256=nfdY2uKgOxHQ1AqUN9Y-L5BxDLd7NiuZf3tt_ef2wvA,6500
@@ -65,7 +66,7 @@ afterpython/tools/prek.py,sha256=NEEGf8alTt9MIelAJ8yxWD-V4mnM_pJ7oHgVQG8pbzo,354
 afterpython/tools/pyproject.py,sha256=Slhxo-Z9M7Gn9ZGL2BKmbPONpDgAJ1g33TdiulxwEyQ,3700
 afterpython/utils.py,sha256=rbCOmRCHif2qzefw9rS-jFA05dz57hZKBr2mxVRaGR0,12406
 afterpython/version.py,sha256=hihRV1S-gc1m46OaXD32ikkEkqzs-Gtq7AcAqOQV-wY,1603
-afterpython-0.4.1.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
-afterpython-0.4.1.dist-info/entry_points.txt,sha256=roa0PDgBueM1JPbRG0G2OSxzaN394OUL_oS9iEwVLBc,80
-afterpython-0.4.1.dist-info/METADATA,sha256=umUYEVFSbdJOdTNhrlnzbZyUHyIjx_ONyIobB4nJbkI,6330
-afterpython-0.4.1.dist-info/RECORD,,
+afterpython-0.4.2.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+afterpython-0.4.2.dist-info/entry_points.txt,sha256=roa0PDgBueM1JPbRG0G2OSxzaN394OUL_oS9iEwVLBc,80
+afterpython-0.4.2.dist-info/METADATA,sha256=kX8jUknJ_OL_frLSqJXss3m4nAt7WrahMaU7SG-67Sk,6416
+afterpython-0.4.2.dist-info/RECORD,,