simplex-web 0.2.0__tar.gz → 0.2.2__tar.gz

{simplex_web-0.2.0 → simplex_web-0.2.2}/.gitignore

@@ -27,8 +27,8 @@ decks/**/slides/files/
 # Generated site
 site/
 
-# Vendored web runtime assets (fetched on demand by simplex.web.vendor)
-src/simplex/web/static/tailwind.js
+# Vendored web runtime assets (fetched/compiled on demand by simplex.web.vendor)
+src/simplex/web/static/tailwind.css
 src/simplex/web/static/htmx.min.js
 src/simplex/web/static/katex/
 src/simplex/web/static/reveal.js/

simplex_web-0.2.2/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: simplex-web
+Version: 0.2.2
+Summary: Manim-slides presentation framework with a generated web portal.
+Project-URL: Homepage, https://github.com/shlomi-perles/simplex
+Project-URL: Issues, https://github.com/shlomi-perles/simplex/issues
+Project-URL: Repository, https://github.com/shlomi-perles/simplex
+Author: Shlomi Perles
+License-Expression: MIT
+License-File: LICENSE
+Keywords: animation,computer-science,education,lecture,manim,manim-slides,math,presentation,static-site
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: av>=15.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: manim-simplex>=0.2.1
+Requires-Dist: manim-slides>=5.1.7
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: mdit-py-plugins>=0.4
+Requires-Dist: pillow>=11.0
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pygments>=2.18
+Requires-Dist: rich>=13.7
+Requires-Dist: structlog>=24.1
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.12
+Requires-Dist: watchfiles>=0.24
+Description-Content-Type: text/markdown
+
+# Simplex
+
+[![PyPI version](https://img.shields.io/pypi/v/simplex-web.svg)](https://pypi.org/project/simplex-web/)
+[![Python](https://img.shields.io/pypi/pyversions/simplex-web.svg)](https://pypi.org/project/simplex-web/)
+[![CI](https://github.com/shlomi-perles/simplex/actions/workflows/ci.yml/badge.svg)](https://github.com/shlomi-perles/simplex/actions/workflows/ci.yml)
+[![License](https://img.shields.io/pypi/l/simplex-web.svg)](https://github.com/shlomi-perles/simplex/blob/main/LICENSE)
+
+Simplex is a Manim presentation workflow with a generated static web portal.
+Write normal Manim scenes, mark slide boundaries with `manim-slides`, and let
+Simplex render the deck, reconcile slide metadata, build thumbnails, render
+notes, and publish a browsable site.
+
+The PyPI distribution is `simplex-web`. It installs the `simplex` command and
+imports into the `simplex.*` namespace.
+
+## Why Simplex?
+
+- Author scenes with standard Manim objects such as `MathTex`, `VGroup`,
+  `Axes`, and `Animation`.
+- Use `manim-simplex` slide bases, layout regions, theme tokens, and mobjects.
+- Organize decks under `decks/` with a small `deck.toml`.
+- Build a static portal with deck pages, notes, citations, math rendering,
+  thumbnails, RevealJS playback, and optional live reload.
+- Keep the rendered video frames clean; navigation chrome lives in the web
+  viewer where it can be changed without re-rendering videos.
+
+## Packages
+
+Simplex is split into a small toolkit:
+
+| Repository | PyPI | Purpose |
+|---|---|---|
+| [`manim-simplex`](https://github.com/shlomi-perles/manim-simplex) | `manim-simplex` | Manim plugin, themes, slide bases, mobjects, and manifest schema. |
+| [`simplex`](https://github.com/shlomi-perles/simplex) | `simplex-web` | CLI, deck discovery, render orchestration, static portal builder. |
+| [`simplex-lectures-template`](https://github.com/shlomi-perles/simplex-lectures-template) | - | Starter lectures repository. |
+
+The import namespace is still `simplex`. Both `manim-simplex` and
+`simplex-web` intentionally use a PEP 420 namespace package so their modules
+merge at runtime.
+
+## Requirements
+
+- Python 3.13 or newer
+- FFmpeg
+- A LaTeX distribution
+- Manim's native dependencies, including Cairo and Pango on Linux
+
+Typical system packages:
+
+```bash
+# Ubuntu / Debian
+sudo apt-get install texlive-latex-extra texlive-fonts-recommended ffmpeg \
+                     libcairo2-dev libpango1.0-dev
+```
+
+```powershell
+# Windows
+winget install MiKTeX.MiKTeX
+winget install Gyan.FFmpeg
+```
+
+After installation, run:
+
+```bash
+simplex doctor
+```
+
+## Install
+
+```bash
+pip install simplex-web
+```
+
+With `uv`:
+
+```bash
+uv add simplex-web
+```
+
+For local development in this repository:
+
+```bash
+uv sync
+uv run simplex doctor
+```
+
+## Quick Start
+
+Create a new deck in an existing project:
+
+```bash
+simplex new algorithms/hash-tables
+simplex render hash-tables
+simplex build
+simplex serve
+```
+
+Then open:
+
+```text
+http://localhost:8000
+```
+
+To start from the GitHub template instead:
+
+```bash
+simplex init my-lectures
+cd my-lectures
+simplex new first-deck
+simplex build
+simplex serve
+```
+
+## Deck Layout
+
+`simplex new hash-tables` creates a deck like this:
+
+```text
+decks/hash-tables/
+|-- deck.toml
+|-- manim.cfg
+|-- notes.md
+|-- refs.bib
+|-- assets/
+`-- slides/
+    |-- __init__.py
+    `-- intro.py
+```
+
+The important fields in `deck.toml` are:
+
+```toml
+slug = "hash-tables"
+title = "Hash Tables"
+summary = "A one-line deck summary."
+theme = "dastimator_dark"
+quality = "high_quality"
+entrypoints = ["slides.intro:Intro"]
+```
+
+`entrypoints` points to scene classes inside the deck directory. Legacy
+`scenes = ["Intro"]` is still accepted for single-file `slides.py` decks, but
+`entrypoints` is the preferred layout.
+
+## Authoring Slides
+
+A scene is ordinary Manim plus the Simplex slide base:
+
+```python
+from manim import DOWN, ORIGIN, Tex, Write
+
+from simplex.slides import BaseSlide
+from simplex.theme.context import get_active_theme
+
+
+class Intro(BaseSlide):
+    def construct(self) -> None:
+        theme = get_active_theme()
+
+        title = Tex("Hello, Simplex", font_size=theme.typography.h1)
+        self.region.place(title, ORIGIN)
+
+        subtitle = Tex(r"$e^{i\pi} + 1 = 0$", font_size=theme.typography.h2)
+        subtitle.next_to(title, DOWN, buff=0.4)
+
+        self.play(Write(title), Write(subtitle))
+        self.next_slide()
+```
+
+`BaseSlide` comes from `manim-simplex`. It provides the default theme,
+bounded layout region, slide lifecycle helpers, and section metadata used by
+the web builder.
+
+## Notes And Site
+
+Each deck can include `notes.md`. The site builder renders Markdown notes,
+inline math, display math, citations from `refs.bib`, and slide references.
+
+Site-wide options live in `site.toml`:
+
+```toml
+brand = "Simplex"
+tagline = "Manim presentations, rendered."
+
+nav = [
+  { label = "Decks", href = "/" },
+  { label = "GitHub", href = "https://github.com/shlomi-perles/simplex" },
+]
+```
+
+Links labeled `GitHub` are shown as the footer GitHub icon, next to the
+`Built with Simplex` mark.
+
+Deployment-only settings are read from environment variables:
+
+- `SIMPLEX_BASE_URL`
+- `SIMPLEX_GA_TAG`
+- `SIMPLEX_BRAND`
+- `SIMPLEX_PREVIEW`
+
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `simplex new <slug>` | Create `decks/<slug>/` from the bundled template. |
+| `simplex new <section>/<slug>` | Create a deck inside a named section. |
+| `simplex init [dir]` | Create a lectures repo from the GitHub template. |
+| `simplex render <slug>` | Render one deck into `site/decks/<slug>/`. |
+| `simplex render <slug>::<Scene>` | Render one scene from a deck. |
+| `simplex build` | Render decks and build the static portal under `site/`. |
+| `simplex build --no-render` | Rebuild portal HTML from existing render output. |
+| `simplex serve [--watch]` | Serve `site/` locally, optionally with live reload. |
+| `simplex test` | Smoke-render decks by rendering only the first animation. |
+| `simplex clean` | Remove generated `site/` and `media/` output. |
+| `simplex doctor` | Check required binaries on `PATH`. |
+
+## Development
+
+```bash
+git clone https://github.com/shlomi-perles/simplex.git
+cd simplex
+uv sync
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+uv run pytest -q
+```
+
+The release workflow uses GitHub Actions Trusted Publishing to upload
+`simplex-web` to PyPI. No PyPI API token is stored in the repository.
+
+## License
+
+MIT.

simplex_web-0.2.2/README.md

@@ -0,0 +1,234 @@
+# Simplex
+
+[![PyPI version](https://img.shields.io/pypi/v/simplex-web.svg)](https://pypi.org/project/simplex-web/)
+[![Python](https://img.shields.io/pypi/pyversions/simplex-web.svg)](https://pypi.org/project/simplex-web/)
+[![CI](https://github.com/shlomi-perles/simplex/actions/workflows/ci.yml/badge.svg)](https://github.com/shlomi-perles/simplex/actions/workflows/ci.yml)
+[![License](https://img.shields.io/pypi/l/simplex-web.svg)](https://github.com/shlomi-perles/simplex/blob/main/LICENSE)
+
+Simplex is a Manim presentation workflow with a generated static web portal.
+Write normal Manim scenes, mark slide boundaries with `manim-slides`, and let
+Simplex render the deck, reconcile slide metadata, build thumbnails, render
+notes, and publish a browsable site.
+
+The PyPI distribution is `simplex-web`. It installs the `simplex` command and
+imports into the `simplex.*` namespace.
+
+## Why Simplex?
+
+- Author scenes with standard Manim objects such as `MathTex`, `VGroup`,
+  `Axes`, and `Animation`.
+- Use `manim-simplex` slide bases, layout regions, theme tokens, and mobjects.
+- Organize decks under `decks/` with a small `deck.toml`.
+- Build a static portal with deck pages, notes, citations, math rendering,
+  thumbnails, RevealJS playback, and optional live reload.
+- Keep the rendered video frames clean; navigation chrome lives in the web
+  viewer where it can be changed without re-rendering videos.
+
+## Packages
+
+Simplex is split into a small toolkit:
+
+| Repository | PyPI | Purpose |
+|---|---|---|
+| [`manim-simplex`](https://github.com/shlomi-perles/manim-simplex) | `manim-simplex` | Manim plugin, themes, slide bases, mobjects, and manifest schema. |
+| [`simplex`](https://github.com/shlomi-perles/simplex) | `simplex-web` | CLI, deck discovery, render orchestration, static portal builder. |
+| [`simplex-lectures-template`](https://github.com/shlomi-perles/simplex-lectures-template) | - | Starter lectures repository. |
+
+The import namespace is still `simplex`. Both `manim-simplex` and
+`simplex-web` intentionally use a PEP 420 namespace package so their modules
+merge at runtime.
+
+## Requirements
+
+- Python 3.13 or newer
+- FFmpeg
+- A LaTeX distribution
+- Manim's native dependencies, including Cairo and Pango on Linux
+
+Typical system packages:
+
+```bash
+# Ubuntu / Debian
+sudo apt-get install texlive-latex-extra texlive-fonts-recommended ffmpeg \
+                     libcairo2-dev libpango1.0-dev
+```
+
+```powershell
+# Windows
+winget install MiKTeX.MiKTeX
+winget install Gyan.FFmpeg
+```
+
+After installation, run:
+
+```bash
+simplex doctor
+```
+
+## Install
+
+```bash
+pip install simplex-web
+```
+
+With `uv`:
+
+```bash
+uv add simplex-web
+```
+
+For local development in this repository:
+
+```bash
+uv sync
+uv run simplex doctor
+```
+
+## Quick Start
+
+Create a new deck in an existing project:
+
+```bash
+simplex new algorithms/hash-tables
+simplex render hash-tables
+simplex build
+simplex serve
+```
+
+Then open:
+
+```text
+http://localhost:8000
+```
+
+To start from the GitHub template instead:
+
+```bash
+simplex init my-lectures
+cd my-lectures
+simplex new first-deck
+simplex build
+simplex serve
+```
+
+## Deck Layout
+
+`simplex new hash-tables` creates a deck like this:
+
+```text
+decks/hash-tables/
+|-- deck.toml
+|-- manim.cfg
+|-- notes.md
+|-- refs.bib
+|-- assets/
+`-- slides/
+    |-- __init__.py
+    `-- intro.py
+```
+
+The important fields in `deck.toml` are:
+
+```toml
+slug = "hash-tables"
+title = "Hash Tables"
+summary = "A one-line deck summary."
+theme = "dastimator_dark"
+quality = "high_quality"
+entrypoints = ["slides.intro:Intro"]
+```
+
+`entrypoints` points to scene classes inside the deck directory. Legacy
+`scenes = ["Intro"]` is still accepted for single-file `slides.py` decks, but
+`entrypoints` is the preferred layout.
+
+## Authoring Slides
+
+A scene is ordinary Manim plus the Simplex slide base:
+
+```python
+from manim import DOWN, ORIGIN, Tex, Write
+
+from simplex.slides import BaseSlide
+from simplex.theme.context import get_active_theme
+
+
+class Intro(BaseSlide):
+    def construct(self) -> None:
+        theme = get_active_theme()
+
+        title = Tex("Hello, Simplex", font_size=theme.typography.h1)
+        self.region.place(title, ORIGIN)
+
+        subtitle = Tex(r"$e^{i\pi} + 1 = 0$", font_size=theme.typography.h2)
+        subtitle.next_to(title, DOWN, buff=0.4)
+
+        self.play(Write(title), Write(subtitle))
+        self.next_slide()
+```
+
+`BaseSlide` comes from `manim-simplex`. It provides the default theme,
+bounded layout region, slide lifecycle helpers, and section metadata used by
+the web builder.
+
+## Notes And Site
+
+Each deck can include `notes.md`. The site builder renders Markdown notes,
+inline math, display math, citations from `refs.bib`, and slide references.
+
+Site-wide options live in `site.toml`:
+
+```toml
+brand = "Simplex"
+tagline = "Manim presentations, rendered."
+
+nav = [
+  { label = "Decks", href = "/" },
+  { label = "GitHub", href = "https://github.com/shlomi-perles/simplex" },
+]
+```
+
+Links labeled `GitHub` are shown as the footer GitHub icon, next to the
+`Built with Simplex` mark.
+
+Deployment-only settings are read from environment variables:
+
+- `SIMPLEX_BASE_URL`
+- `SIMPLEX_GA_TAG`
+- `SIMPLEX_BRAND`
+- `SIMPLEX_PREVIEW`
+
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `simplex new <slug>` | Create `decks/<slug>/` from the bundled template. |
+| `simplex new <section>/<slug>` | Create a deck inside a named section. |
+| `simplex init [dir]` | Create a lectures repo from the GitHub template. |
+| `simplex render <slug>` | Render one deck into `site/decks/<slug>/`. |
+| `simplex render <slug>::<Scene>` | Render one scene from a deck. |
+| `simplex build` | Render decks and build the static portal under `site/`. |
+| `simplex build --no-render` | Rebuild portal HTML from existing render output. |
+| `simplex serve [--watch]` | Serve `site/` locally, optionally with live reload. |
+| `simplex test` | Smoke-render decks by rendering only the first animation. |
+| `simplex clean` | Remove generated `site/` and `media/` output. |
+| `simplex doctor` | Check required binaries on `PATH`. |
+
+## Development
+
+```bash
+git clone https://github.com/shlomi-perles/simplex.git
+cd simplex
+uv sync
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+uv run pytest -q
+```
+
+The release workflow uses GitHub Actions Trusted Publishing to upload
+`simplex-web` to PyPI. No PyPI API token is stored in the repository.
+
+## License
+
+MIT.

{simplex_web-0.2.0 → simplex_web-0.2.2}/pyproject.toml

@@ -32,7 +32,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-  "manim-simplex>=0.2.0",
+  "manim-simplex>=0.2.1",
   "manim-slides>=5.1.7",
   "pydantic>=2.7",
   "pydantic-settings>=2.3",
@@ -72,7 +72,7 @@ license-files = ["LICENSE"]
 name = "simplex-web"
 readme = "README.md"
 requires-python = ">=3.13"
-version = "0.2.0"
+version = "0.2.2"
 
 [project.scripts]
 simplex = "simplex.cli.commands:app"
@@ -109,7 +109,7 @@ artifacts = [
   "src/simplex/web/static/htmx.min.js",
   "src/simplex/web/static/katex/**/*",
   "src/simplex/web/static/reveal.js/**/*",
-  "src/simplex/web/static/tailwind.js",
+  "src/simplex/web/static/tailwind.input.css",
 ]
 only-include = [
   "LICENSE",
@@ -130,7 +130,7 @@ artifacts = [
   "src/simplex/web/static/htmx.min.js",
   "src/simplex/web/static/katex/**/*",
   "src/simplex/web/static/reveal.js/**/*",
-  "src/simplex/web/static/tailwind.js",
+  "src/simplex/web/static/tailwind.input.css",
 ]
 packages = ["src/simplex"]
 

{simplex_web-0.2.0 → simplex_web-0.2.2}/src/simplex/deck/_template/deck.toml

@@ -1,11 +1,10 @@
+created_at = "__CREATED_AT__"
+entrypoints = ["slides.intro:Intro"]
+order = 1000
+quality = "high_quality"
 slug = "__SLUG__"
-title = "__TITLE__"
 summary = "Replace with a one-line description."
 tags = []
 theme = "dastimator_dark"
-quality = "high_quality"
+title = "__TITLE__"
 voiceover = false
-category = ""
-created_at = "__CREATED_AT__"
-order = 1000
-entrypoints = ["slides.intro:Intro"]

{simplex_web-0.2.0 → simplex_web-0.2.2}/src/simplex/web/builder.py

@@ -18,6 +18,7 @@ No render cache. Manim's per-animation cache + ``save_sections=True``
 """
 
 import contextlib
+import hashlib
 import shutil
 import subprocess
 from datetime import UTC, datetime, time
@@ -36,6 +37,28 @@ from simplex.web.bibliography import Bibliography
 from simplex.web.site_config import SiteConfig
 
 
+def _static_source_dir() -> Path:
+    return Path(__file__).parent / "static"
+
+
+def _file_version(path: Path) -> str:
+    """Short content hash for cache-busting generated asset URLs."""
+    if not path.exists() or not path.is_file():
+        return ""
+    digest = hashlib.blake2s(digest_size=6)
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _with_version(url: str, version: str) -> str:
+    if not version:
+        return url
+    separator = "&" if "?" in url else "?"
+    return f"{url}{separator}v={version}"
+
+
 def _jinja(site_cfg: SiteConfig) -> Environment:
     env = Environment(
         loader=PackageLoader("simplex.web", "templates"),
@@ -45,7 +68,9 @@ def _jinja(site_cfg: SiteConfig) -> Environment:
     )
 
     def static(path: str) -> str:
-        return site_cfg.url("static/" + path.lstrip("/"))
+        clean = path.lstrip("/")
+        url = site_cfg.url("static/" + clean)
+        return _with_version(url, _file_version(_static_source_dir() / clean))
 
     globals_: dict[str, Any] = cast(dict[str, Any], env.globals)
     globals_["static"] = static
@@ -55,13 +80,13 @@ def _jinja(site_cfg: SiteConfig) -> Environment:
 
 def _copy_static(site_dir: Path) -> None:
     """Copy bundled static assets into ``site/static/``."""
-    src = Path(__file__).parent / "static"
+    src = _static_source_dir()
     src.mkdir(parents=True, exist_ok=True)
     vendor.ensure(src)
     dst = site_dir / "static"
     dst.mkdir(parents=True, exist_ok=True)
     for entry in src.iterdir():
-        if entry.name in {"README.md", ".gitkeep"}:
+        if entry.name in {"README.md", ".gitkeep", "tailwind.input.css"}:
             continue
         target = dst / entry.name
         if entry.is_dir():
@@ -178,7 +203,7 @@ def _build_deck(
         for main in manifest.main_slides
     )
 
-    html.render_html(
+    slides_html = html.render_html(
         deck,
         manifest.model_copy(update={"main_slides": enriched}),
         output_dir=deck_out,
@@ -206,6 +231,7 @@ def _build_deck(
         has_notes_pdf=_has_notes_pdf(deck_out),
         notes_html=notes_html,
         palette_css=render_web_css(deck.resolved_web_palette()),
+        slides_version=_file_version(slides_html),
     )
     (deck_out / "index.html").write_text(page, encoding="utf-8")
     return (

{simplex_web-0.2.0 → simplex_web-0.2.2}/src/simplex/web/sidenotes.py

@@ -69,7 +69,9 @@ def _extract_bodies(html: str) -> dict[str, str]:
 
 def _render_sidenote(n: str, num: str, body: str) -> str:
     return (
-        f'<label for="sn-toggle-{n}" class="sidenote-ref" id="snref-{n}">{num}</label>'
+        f'<label for="sn-toggle-{n}" class="sidenote-ref" id="snref-{n}" '
+        f'role="button" tabindex="0" aria-controls="sn-{n}" aria-expanded="false">'
+        f"{num}</label>"
         f'<input type="checkbox" id="sn-toggle-{n}" class="sidenote-toggle" '
         'aria-hidden="true" />'
         f'<aside class="sidenote" id="sn-{n}" role="note">{body}</aside>'

{simplex_web-0.2.0 → simplex_web-0.2.2}/src/simplex/web/site_config.py

@@ -9,6 +9,7 @@ import os
 import tomllib
 from pathlib import Path
 from typing import Any, Self
+from urllib.parse import urlparse
 
 from pydantic import BaseModel, ConfigDict
 
@@ -44,6 +45,17 @@ class SiteConfig(BaseModel):
             return f"/{clean}"
         return f"{base}/{clean}"
 
+    def is_external_url(self, href: str) -> bool:
+        """Return true for links that should not be prefixed by `base_url`."""
+        parsed = urlparse(href)
+        return bool(parsed.scheme or parsed.netloc)
+
+    def nav_url(self, href: str) -> str:
+        """Resolve a committed nav href without breaking external links."""
+        if self.is_external_url(href) or href.startswith("#"):
+            return href
+        return self.url(href)
+
     @classmethod
     def load(cls, repo_root: Path | None = None) -> Self:
         repo_root = repo_root or Path.cwd()