afterpython 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

afterpython/builders/__init__.py

@@ -1,17 +1,25 @@
 from afterpython.builders.content_json import build_content_json
+from afterpython.builders.faq_json import build_faq_json
 from afterpython.builders.index_md import (
     create_placeholder_index_md_files,
     delete_placeholder_index_md_files,
 )
 from afterpython.builders.jupyter_notebook import build_jupyter_notebooks
+from afterpython.builders.llms_txt import build_llms_txt
+from afterpython.builders.marimo_notebook import build_marimo_readme
 from afterpython.builders.markdown import build_markdown
 from afterpython.builders.metadata import build_metadata
+from afterpython.builders.url_md import build_url_md
 
 __all__ = (
     "build_content_json",
+    "build_faq_json",
     "build_jupyter_notebooks",
+    "build_llms_txt",
+    "build_marimo_readme",
     "build_markdown",
     "build_metadata",
+    "build_url_md",
     "create_placeholder_index_md_files",
     "delete_placeholder_index_md_files",
 )

afterpython/builders/faq_json.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import json
+
+import click
+
+import afterpython as ap
+from afterpython._io.yaml import read_yaml
+
+build_path = ap.paths.build_path
+
+
+def build_faq_json():
+    """Build faq.json from the user's afterpython/faq.yml.
+
+    Output shape: a flat list of {question, answer, category}. `category` is
+    always present — empty string when unset — so the frontend can rely on a
+    uniform item shape. Order is preserved so the frontend can derive category
+    order from first appearance.
+    """
+    faq_yml_path = ap.paths.afterpython_path / "faq.yml"
+
+    if not faq_yml_path.exists():
+        click.echo("No faq.yml found, skip building faq.json")
+        return
+
+    click.echo("Building faq.json...")
+
+    raw = read_yaml(faq_yml_path)
+    if raw is None:
+        items: list[dict] = []
+    else:
+        items = [
+            {
+                "question": str(item["question"]),
+                "answer": str(item["answer"]),
+                "category": str(item["category"]) if item.get("category") else "",
+            }
+            for item in raw
+        ]
+
+    with open(build_path / "faq.json", "w") as f:
+        json.dump(items, f, indent=2)

afterpython/builders/jupyter_notebook.py

@@ -5,24 +5,11 @@ from pathlib import Path
 import click
 
 import afterpython as ap
+from afterpython.builders.marimo_notebook import _create_molab_url, _get_molab_badge
 from afterpython.const import CONTENT_TYPES
 from afterpython.tools.pyproject import read_metadata
 
 
-def _get_molab_badge() -> str:
-    return "https://marimo.io/molab-shield.svg"
-
-
-def _create_molab_url(github_url: str, content_path: Path):
-    """Create a molab URL for a given content type and notebook path.
-    Args:
-        github_url: str, e.g. "https://github.com/AfterPythonOrg/afterpython"
-        content_path: str, e.g. "tutorial/test.ipynb"
-    """
-    github_url = github_url.replace("https://github.com/", "github/")
-    return f"https://molab.marimo.io/{github_url}/blob/main/afterpython/{content_path.as_posix()}"
-
-
 def _read_notebook(notebook_path: Path, content_path: Path) -> dict | None:
     """Read and validate a Jupyter notebook.
 

afterpython/builders/llms_txt.py

@@ -0,0 +1,248 @@
+# VIBE-CODED
+"""Build llms.txt — a single catalog of the site for AI agents.
+
+Output: `afterpython/_website/static/llms.txt`. SvelteKit's static adapter
+serves it at `/llms.txt` so agents (Claude, GPT, etc.) can fetch a curated
+overview of the project + a link list of every published page.
+
+Conforms to the llms.txt convention (https://llmstxt.org/): a markdown file
+with a project H1, optional context paragraphs, and `## Section` headings
+each containing a link list.
+
+Flow
+----
+build_llms_txt()                                      # entry point
+  ├─ _read_readme() + _standardize_readme()           # → header content
+  └─ for each content_type in ORDERED_CONTENT_TYPES:
+       └─ _list_pages(content_type)                    # → [(title, url, abstract)]
+            (skips entries whose source .md no longer exists — those were
+             auto-generated placeholder index.md files deleted in postbuild)
+       └─ _format_section(content_type, blurb, entries)
+            ├─ heading: SECTION_HEADINGS[content_type]
+            ├─ blurb:   project.description from afterpython/{type}/myst.yml
+            └─ entries: `- [Title](/type/slug.md): abstract`
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+import click
+
+import afterpython as ap
+from afterpython._typing import tContentType
+from afterpython.const import CONTENT_TYPES
+
+# A line whose entire content is a markdown image (badge), with optional
+# link wrapper and optional HTML-comment wrapper.
+#   matches: ![alt](url)
+#            [![alt](url)](link)
+#            <!-- ![alt](url) -->
+#            <!-- [![alt](url)](link) -->
+# Anchored ^...$ so inline references in body prose are NOT matched.
+_BADGE_LINE = re.compile(
+    r"""
+    ^\s*                # leading whitespace
+    (?:<!--\s*)?        # optional HTML comment open
+    \[?                 # optional link open  '['
+    !\[[^\]]*\]         # ![alt]
+    \([^)]+\)           # (image_url)
+    (?:\]\([^)]+\))?    # optional  ](link_url)
+    (?:\s*-->)?         # optional HTML comment close
+    \s*$                # trailing whitespace
+    """,
+    re.VERBOSE,
+)
+
+# Order in which content-type sections appear in llms.txt. Sections with zero
+# entries are skipped. Reasoning: an agent answering "how do I X?" should hit
+# concepts first (doc), then how-to (tutorial/guide), then examples, then
+# background (blog) — strongest signal first.
+ORDERED_CONTENT_TYPES: list[tContentType] = [
+    "doc",
+    "tutorial",
+    "guide",
+    "example",
+    "blog",
+]
+
+# One-line hint that sits between the README and the section list, telling
+# an LLM reading llms.txt that the URLs below are fetchable markdown sources
+# (the Mintlify / Anthropic-docs convention). Costs ~20 tokens and removes
+# any ambiguity about what fetching `/doc/quickstart.md` returns.
+LINK_NOTE = (
+    "> Every link below points to the raw markdown source of the page."
+    " Fetch any URL directly to read its content as markdown."
+)
+
+# Human-readable display name for each content type's `## ` heading in llms.txt.
+SECTION_HEADINGS: dict[tContentType, str] = {
+    "doc": "Documentation",
+    "tutorial": "Tutorials",
+    "guide": "Guides",
+    "example": "Examples",
+    "blog": "Blog",
+}
+
+# Defensive sync check: if a new content type is added to const.CONTENT_TYPES,
+# the developer must remember to slot it into ORDERED_CONTENT_TYPES and
+# SECTION_HEADINGS. Import-time failure beats a silently-missing section.
+assert set(ORDERED_CONTENT_TYPES) == CONTENT_TYPES, (
+    "ORDERED_CONTENT_TYPES is out of sync with const.CONTENT_TYPES"
+)
+assert set(SECTION_HEADINGS.keys()) == CONTENT_TYPES, (
+    "SECTION_HEADINGS is out of sync with const.CONTENT_TYPES"
+)
+
+
+def _read_readme() -> str:
+    """Read the project's README.md from repo root, verbatim. Empty string if
+    the README is missing (e.g. brand new project)."""
+    readme_path = ap.paths.user_path / "README.md"
+    if not readme_path.exists():
+        return ""
+    return readme_path.read_text(encoding="utf-8")
+
+
+def _standardize_readme(text: str) -> str:
+    """Clean the README before embedding it in llms.txt.
+
+    Currently strips badges (shields, download counters, etc.) from the
+    README's *header zone* — everything before the first `## ` heading —
+    since they're chrome for human readers and noise for LLMs.
+
+    The header-zone restriction protects content images that legitimately
+    appear later in the README (e.g. the `<picture>` website screenshot
+    after the first H2 — also untouched because it's HTML, not a markdown
+    image).
+
+    Future ideas if more cleanup is wanted: strip GitHub-flavored anchor
+    links, install commands, "table of contents" sections.
+    """
+    lines = text.split("\n")
+
+    # Boundary of the header zone: index of the first `## ` line, or end of
+    # file if no H2 exists.
+    boundary = next(
+        (i for i, line in enumerate(lines) if line.startswith("## ")),
+        len(lines),
+    )
+
+    cleaned_header = [line for line in lines[:boundary] if not _BADGE_LINE.match(line)]
+    rejoined = "\n".join(cleaned_header + lines[boundary:])
+
+    # After removing 9 consecutive badge lines, you can end up with a stack
+    # of blanks where they used to be. Collapse 3+ newlines to 2 (one blank).
+    return re.sub(r"\n{3,}", "\n\n", rejoined)
+
+
+def _read_section_blurb(content_type: tContentType) -> str | None:
+    """Pull the section's one-line blurb from `afterpython/{type}/myst.yml`'s
+    `project.description`.
+
+    Returns None if myst.yml is missing or has no description set — in which
+    case the section in llms.txt simply omits the `> blurb` line.
+    """
+    from afterpython._io.yaml import read_yaml
+
+    myst_yml = ap.paths.afterpython_path / content_type / "myst.yml"
+    if not myst_yml.exists():
+        return None
+
+    data = read_yaml(myst_yml) or {}
+    description = data.get("project", {}).get("description")
+    return str(description).strip() if description else None
+
+
+def _list_pages(content_type: tContentType) -> list[tuple[str, str, str | None]]:
+    """Return `[(title, url, abstract), ...]` for each page MyST built.
+
+    Reads MyST's `_build/site/content/*.json` files (which already have
+    title, slug, and frontmatter resolved — no need to re-parse source).
+    Skips entries whose source .md no longer exists; those were auto-generated
+    placeholder index.md files that `delete_placeholder_index_md_files`
+    removed at the start of postbuild.
+    """
+    content_dir = ap.paths.afterpython_path / content_type
+    myst_content_dir = content_dir / "_build" / "site" / "content"
+    if not myst_content_dir.exists():
+        return []
+
+    pages: list[tuple[str, str, str | None]] = []
+    for json_file in sorted(myst_content_dir.glob("*.json")):
+        try:
+            data = json.loads(json_file.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            continue
+
+        # Filter placeholder index.md entries: their source has been deleted.
+        location = data.get("location", "")
+        source_md = content_dir / location.lstrip("/")
+        if not source_md.exists():
+            continue
+
+        slug = data.get("slug")
+        if not slug:
+            continue
+
+        frontmatter = data.get("frontmatter", {})
+        title = frontmatter.get("title") or slug
+        abstract = frontmatter.get("abstract")
+
+        url = f"/{content_type}/{slug}.md"
+        pages.append((title, url, abstract))
+    return pages
+
+
+def _format_link_entry(title: str, url: str, abstract: str | None) -> str:
+    """One line of the link list.
+
+    With abstract:    `- [Title](url): abstract`
+    Without abstract: `- [Title](url)`
+    """
+    if abstract:
+        return f"- [{title}]({url}): {abstract.strip()}"
+    return f"- [{title}]({url})"
+
+
+def _format_section(
+    content_type: tContentType,
+    blurb: str | None,
+    entries: list[tuple[str, str, str | None]],
+) -> str:
+    """Format one `## Section`: heading, optional blurb, link list."""
+    parts = [f"## {SECTION_HEADINGS[content_type]}", ""]
+    if blurb:
+        parts.extend([f"> {blurb}", ""])
+    for title, url, abstract in entries:
+        parts.append(_format_link_entry(title, url, abstract))
+    return "\n".join(parts)
+
+
+def build_llms_txt() -> None:
+    """Generate `_website/static/llms.txt` — one catalog file for the site.
+
+    Runs at the end of `postbuild()` after MyST output is finalized and
+    placeholder index.md files have been removed.
+    """
+    readme = _standardize_readme(_read_readme())
+
+    sections: list[str] = []
+    total_entries = 0
+    for content_type in ORDERED_CONTENT_TYPES:
+        entries = _list_pages(content_type)
+        if not entries:
+            continue
+        blurb = _read_section_blurb(content_type)
+        sections.append(_format_section(content_type, blurb, entries))
+        total_entries += len(entries)
+
+    body = readme.rstrip()
+    if sections:
+        body = body + "\n\n" + LINK_NOTE + "\n\n" + "\n\n".join(sections) + "\n"
+
+    output = ap.paths.website_path / "static" / "llms.txt"
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(body, encoding="utf-8")
+    click.echo(f"Generated {output} ({total_entries} entries)")

afterpython/builders/marimo_notebook.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Literal
+
+import click
+
+import afterpython as ap
+from afterpython.tools.pyproject import read_metadata
+
+MarimoExportMode = Literal["wasm", "static"]
+
+
+def _get_molab_badge() -> str:
+    return "https://marimo.io/molab-shield.svg"
+
+
+def _create_molab_url(github_url: str, content_path: Path) -> str:
+    """Create a molab URL for a marimo notebook at content_path (relative to afterpython/)."""
+    github_url = github_url.replace("https://github.com/", "github/")
+    return f"https://molab.marimo.io/{github_url}/blob/main/afterpython/{content_path.as_posix()}"
+
+
+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.
+    """
+    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]
+    except OSError:
+        return False
+    return "__generated_with" in head and "marimo.App(" in head
+
+
+def _export_marimo(source: Path, output_html: Path, mode: MarimoExportMode):
+    """Run `marimo export` to produce HTML at `output_html`."""
+    output_html.parent.mkdir(parents=True, exist_ok=True)
+    subcommand = "html-wasm" if mode == "wasm" else "html"
+    cmd = ["marimo", "export", subcommand, str(source), "-o", str(output_html)]
+    # WASM-only flag: --mode edit shows code cells (interactive). Without it,
+    # marimo's html-wasm subcommand defaults to "run" which hides them.
+    if mode == "wasm":
+        cmd += ["--mode", "edit"]
+    result = subprocess.run(cmd, check=False)
+    if result.returncode != 0:
+        raise click.ClickException(f"marimo export failed for {source}")
+
+
+def _inject_molab_badge(html_path: Path, molab_url: str):
+    """Insert a fixed-position molab badge near the top of the exported HTML body.
+
+    Used so users can run the notebook on a real Python server (molab) when the
+    static export can't execute, or as an alternative to the in-page WASM kernel.
+    """
+    if not html_path.exists():
+        return
+    html = html_path.read_text(encoding="utf-8")
+    badge = (
+        f'<a href="{molab_url}" target="_top" rel="noopener" '
+        # right offset clears marimo's circular toolbar buttons in edit mode;
+        # top offset is hand-tuned to vertically center against those buttons
+        # (we can't group with marimo's UI, so this is a visual eyeball)
+        f'style="position:fixed;top:16px;right:100px;z-index:9999;">'
+        f'<img src="{_get_molab_badge()}" alt="Open in molab" />'
+        f"</a>"
+    )
+    new_html, n = re.subn(r"(<body[^>]*>)", r"\1" + badge, html, count=1)
+    if n == 0:
+        click.echo(f"⚠ Could not locate <body> in {html_path}, skipping molab badge")
+        return
+    html_path.write_text(new_html, encoding="utf-8")
+
+
+def build_marimo_notebook(
+    source: Path,
+    output_html: Path,
+    content_path: Path,
+    mode: MarimoExportMode = "wasm",
+):
+    """Build a single marimo notebook to HTML and inject the molab badge.
+
+    Generic core for marimo builds — keep this notebook-agnostic so future
+    callers (e.g. content-type builds in blog/tutorial) can reuse it.
+
+    Args:
+        source: Path to the marimo .py file.
+        output_html: Path to write the exported HTML to.
+        content_path: Path of `source` relative to afterpython/, used to build
+            the molab URL (which assumes the file lives under afterpython/ on
+            the user's GitHub repo).
+        mode: "wasm" (interactive, Pyodide) or "static" (pre-rendered).
+    """
+    if not is_marimo_notebook(source):
+        click.echo(f"{source} is not a marimo notebook, skip building")
+        return
+
+    click.echo(f"Building marimo notebook {source.name} (mode={mode})...")
+    _export_marimo(source, output_html, mode)
+
+    # WASM mode runs the notebook in-browser via Pyodide, so molab (a remote
+    # runtime) is redundant. Skip the badge.
+    if mode == "wasm":
+        return
+
+    add_molab_badge = os.getenv("AP_MOLAB_BADGE", "1") == "1"
+    if not add_molab_badge:
+        return
+
+    metadata = read_metadata()
+    github_url = (
+        metadata.urls.get("repository") if "repository" in metadata.urls else None
+    )
+    if not github_url:
+        click.echo(
+            "⚠ Repository URL not found in [project.urls] in pyproject.toml, "
+            "skipping molab badge"
+        )
+        return
+
+    molab_url = _create_molab_url(github_url, content_path)
+    _inject_molab_badge(output_html, molab_url)
+
+
+def build_marimo_readme(mode: MarimoExportMode = "wasm"):
+    """Build afterpython/README.py to _build/readme_py/readme_py.html.
+
+    Skips silently if README.py is absent or isn't a marimo notebook so users
+    who keep only README.md aren't penalized.
+    """
+    readme_path = ap.paths.afterpython_path / "README.py"
+    if not readme_path.exists():
+        return
+    output_html = ap.paths.build_path / "readme_py" / "readme_py.html"
+    content_path = Path("README.py")
+    build_marimo_notebook(readme_path, output_html, content_path, mode)

afterpython/builders/metadata.py

@@ -36,15 +36,48 @@ def convert_paths():
 
 
 def build_metadata():
-    """Build metadata.json using pyproject.toml"""
+    """Build metadata.json using pyproject.toml + afterpython.toml.
+
+    Adds two frontend-only fields sourced from `[website]` in afterpython.toml:
+    - `announcement`: markdown banner string (empty when unset)
+    - `readme_py`: "wasm" | "static" | "" — resolved to "" when README.py is
+      missing or isn't a marimo notebook, so the frontend can use a single
+      truthiness check to decide between iframe and markdown description.
+    """
+    from afterpython._io.toml import _from_tomlkit
+    from afterpython.tools._afterpython import read_afterpython
     from afterpython.tools.pyproject import read_metadata
 
     click.echo("Building metadata.json...")
 
     metadata: StandardMetadata = read_metadata()
+    metadata_json = metadata.as_json()
+
+    afterpython = read_afterpython()
+    website = _from_tomlkit(afterpython.get("website", {}))
+    metadata_json["announcement"] = str(website.get("announcement", "")).strip()
+    metadata_json["readme_py"] = _resolve_readme_py(website)
 
-    # Write to metadata.json
     with open(build_path / "metadata.json", "w") as f:
-        json.dump(metadata.as_json(), f, indent=2)
+        json.dump(metadata_json, f, indent=2)
 
     convert_paths()
+
+
+def _resolve_readme_py(website_config: dict) -> str:
+    """Resolve the readme_py field for metadata.json.
+
+    Returns "wasm" | "static" only when afterpython/README.py exists AND is a
+    marimo notebook, so the toml setting is honored only when there's actually
+    something to render. Otherwise returns "".
+    """
+    from afterpython.builders.marimo_notebook import is_marimo_notebook
+
+    readme_path = ap.paths.afterpython_path / "README.py"
+    if not is_marimo_notebook(readme_path):
+        return ""
+
+    mode = str(website_config.get("readme_py", "wasm"))
+    if mode not in ("wasm", "static"):
+        return "wasm"
+    return mode

afterpython/builders/url_md.py

@@ -0,0 +1,107 @@
+# VIBE-CODED
+"""Publish raw markdown alongside rendered HTML.
+
+For every page the website serves at `/{type}/{slug}`, also publish the source
+markdown at `/{type}/{slug}.md`. Lets LLMs and AI agents fetch clean content
+without HTML chrome (the Mintlify / Anthropic-docs pattern).
+
+Output goes into `afterpython/_website/static/{type}/{slug}.md`. SvelteKit's
+static adapter then serves each file at the matching URL with no SvelteKit-side
+code changes.
+
+Flow
+----
+build_url_md()                                        # entry point
+  └─ for each content_type in CONTENT_TYPES:
+       └─ for each `*.md` / `*.ipynb` under afterpython/{type}/:
+            ├─ _slugify(stem)                         → URL slug
+            ├─ .md    → shutil.copy(source, dest)    (frontmatter preserved)
+            └─ .ipynb → jupytext.read + write(fmt="md") (cell outputs stripped)
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import click
+import jupytext
+
+import afterpython as ap
+from afterpython._typing import tContentType
+from afterpython.const import CONTENT_TYPES
+
+
+def _slugify(stem: str) -> str:
+    """Mirror MyST's URL slug rule so each `.md` lands at the same URL as its
+    rendered HTML sibling.
+
+    `package_management.md` -> `/doc/package-management.md`
+    `CONTRIBUTING.md`       -> `/doc/contributing.md`
+    """
+    return stem.lower().replace("_", "-")
+
+
+def _publish_md(source: Path, dest: Path) -> None:
+    """Copy a `.md` source verbatim. Frontmatter is preserved — LLMs can use
+    it (date, authors, tags) and it's harmless if ignored.
+    """
+    shutil.copy(source, dest)
+
+
+def _publish_ipynb(source: Path, dest: Path) -> None:
+    """Convert a notebook to clean markdown via jupytext.
+
+    jupytext strips cell outputs by default, producing a leaner file than
+    `nbconvert` would. The `md` format is jupytext's default — clean enough
+    for LLM consumption while still round-trippable if anyone needs the
+    notebook back.
+    """
+    notebook = jupytext.read(source)
+    jupytext.write(notebook, dest, fmt="md")
+
+
+def _publish_for_type(content_type: tContentType) -> int:
+    """Walk one content type's source dir; publish every supported file.
+    Returns the number of files written.
+    """
+    source_dir = ap.paths.afterpython_path / content_type
+    if not source_dir.exists():
+        return 0
+
+    dest_dir = ap.paths.website_path / "static" / content_type
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    count = 0
+    for source in sorted(source_dir.rglob("*")):
+        if "_build" in source.parts:
+            continue
+        if not source.is_file():
+            continue
+
+        slug = _slugify(source.stem)
+        dest = dest_dir / f"{slug}.md"
+
+        if source.suffix == ".md":
+            _publish_md(source, dest)
+        elif source.suffix == ".ipynb":
+            _publish_ipynb(source, dest)
+        else:
+            continue
+
+        count += 1
+    return count
+
+
+def build_url_md() -> None:
+    """Publish raw markdown for every content type alongside the rendered HTML.
+
+    Runs as part of `postbuild()` after MyST's HTML has been copied into
+    `_website/static/{type}/`. Each `.md` ends up as a sibling of the rendered
+    `{slug}/index.html`, served at `/{type}/{slug}.md` by SvelteKit's static
+    adapter.
+    """
+    for content_type in CONTENT_TYPES:
+        count = _publish_for_type(content_type)
+        if count > 0:
+            click.echo(f"Published {count} url-md file(s) for {content_type}/")