sphinx-typst-render 0.2.0__tar.gz

sphinx_typst_render-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NB-TUDelft and K.Zabłocki (Zamkorus)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sphinx_typst_render-0.2.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: sphinx-typst-render
+Version: 0.2.0
+Summary: Render Typst sources into downloadable PDFs and inline previews in Sphinx and Jupyter Book.
+Keywords: jupyter-book,sphinx,typst,pdf,forms,documentation
+Author: NB-TUDelft, K.Zabłocki (Zamkorus)
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Sphinx
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Topic :: Software Development :: Documentation
+Requires-Dist: sphinx>=7
+Requires-Dist: typst>=0.15
+Requires-Dist: typst-fillable>=0.0.1
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/NB-TUDelft/sphinx-typst-render
+Project-URL: Repository, https://github.com/NB-TUDelft/sphinx-typst-render
+Project-URL: Issues, https://github.com/NB-TUDelft/sphinx-typst-render/issues
+Project-URL: Changelog, https://github.com/NB-TUDelft/sphinx-typst-render/releases
+Description-Content-Type: text/markdown
+
+# sphinx-typst-render
+
+Compile [Typst](https://typst.app) sources during a Sphinx or Jupyter Book
+build. Each source becomes a PDF students can download, plus an optional inline
+preview image that follows the page theme.
+
+Typst ships inside the [`typst`](https://pypi.org/project/typst/) wheel as a
+statically linked extension module, so there is no `typst` CLI to install and no
+Rust toolchain on the build machine.
+
+## Install
+
+```bash
+pip install sphinx-typst-render
+```
+
+## Enable
+
+In a Jupyter Book `_config.yml`:
+
+```yaml
+sphinx:
+  extra_extensions:
+    - sphinx_typst_render
+```
+
+In a plain Sphinx `conf.py`:
+
+```python
+extensions = ["sphinx_typst_render"]
+```
+
+## Use
+
+````markdown
+```{typst} worksheets/week3.typ
+:label: Week 3 worksheet
+```
+````
+
+The block renders **nothing into the page**. It compiles `worksheets/week3.typ`
+and adds the resulting PDF to the theme's download menu, beside the page's own
+`.ipynb` and `.pdf` entries, under a heading you configure.
+
+Pass `:inline:` to also show a preview image and a download link in the body.
+
+### Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `:preview:` | `none`, or `svg` with `:inline:` | `svg`, `png`, or `none`. |
+| `:page:` | `1` | Which page to preview in a multi page document. |
+| `:height:` | unset | Height of the preview image, e.g. `420px`. |
+| `:alt:` | generated | Alt text for the preview image. |
+| `:label:` | generated | Text of the download link. |
+| `:ppi:` | `144` | Resolution of a `png` preview. |
+| `:class:` | none | Extra CSS classes on the wrapper. |
+| `:inline:` | off | Also show a preview and link in the page body. |
+| `:fillable:` | off | Add interactive form fields. See below. |
+
+### Configuration
+
+| Value | Default | Meaning |
+| --- | --- | --- |
+| `typst_render_preview` | `"svg"` | Default for `:preview:`. |
+| `typst_render_ppi` | `144.0` | Default for `:ppi:`. |
+| `typst_render_stage_field_library` | `True` | Stage `capture_field.typ` into the source root. |
+| `typst_render_source_label` | `"Source"` | Heading above the page's own downloads. |
+| `typst_render_downloads_label` | `"Worksheets"` | Heading above the rendered PDFs. |
+
+## The download menu
+
+Rendered PDFs are added to the download dropdown that sphinx-book-theme puts in
+the article header, so students find them where they already look for the page
+source. Two headings separate the groups, and both are configurable because
+what the page *is* differs per project:
+
+```yaml
+sphinx:
+  config:
+    typst_render_source_label: Manual      # or Chapter, Page, Book
+    typst_render_downloads_label: Worksheets
+```
+
+That renders as:
+
+```
+Manual
+  .ipynb
+  .pdf
+Worksheets
+  Organizer 1.1 (fillable)
+```
+
+Set either to an empty string to leave that group unlabelled.
+
+The headings are inserted by a small stylesheet and script shipped with this
+package. They are not built server side because the theme's button macro
+dispatches on a fixed set of item types and forces its own CSS class, so a
+non-link entry cannot be expressed through the `header_buttons` context.
+
+Without a theme that provides such a menu, the PDFs are still written and
+copied, and a warning names the page whose downloads are unreachable. Use
+`:inline:` in that case.
+
+## Why SVG previews
+
+With `:inline:`, an SVG preview is line art, so a theme that inverts diagrams for dark mode
+handles it correctly, and it stays sharp at any zoom. Use `:preview: png` for a
+worksheet that contains photographs, and pair it with whatever class your theme
+uses to opt out of inversion:
+
+````markdown
+```{typst} worksheets/week5.typ
+:preview: png
+:class: no-invert
+```
+````
+
+## Fillable PDFs
+
+Typst cannot emit interactive form fields on its own. Support is requested in
+[typst/typst#1765](https://github.com/typst/typst/issues/1765) and is still
+open. This package therefore delegates to
+[typst-fillable](https://github.com/carpe-diem/typst-fillable), which reads
+field geometry back out of the compiled document with `typst.query()`, draws a
+transparent AcroForm overlay with ReportLab, and merges it with pypdf.
+
+Mark fields in the Typst source with the helper, then add `:fillable:`:
+
+```typ
+#import "/_typst_lib/capture_field.typ": text_field, checkbox_field, textarea_field
+
+Measured $U_(i n)$: #text_field("u_in", width: 80pt)
+
+Did the output clip? #checkbox_field("clipped")
+
+Explain the discrepancy:
+#textarea_field("discussion", height: 60pt)
+```
+
+`capture_field.typ` is staged into `_typst_lib/` at the root of your Sphinx
+source directory on every build, so the import path above is stable wherever the
+worksheet lives. Set `typst_render_stage_field_library = False` to manage it
+yourself.
+
+Available helpers are `text_field`, `textarea_field`, `checkbox_field`, and
+`radio_field`, plus the lower level `capture_field`.
+
+## Caching
+
+Output is written beside the source and skipped when nothing relevant changed.
+The cache key covers the source, every other `.typ` file in the same folder, the
+staged helper, and the render options.
+
+Imports that reach outside the source folder are not tracked. Keep shared
+partials next to the worksheets that use them, or touch the importing file to
+force a rebuild.
+
+Add the generated artefacts to `.gitignore`:
+
+```gitignore
+*.typst-stamp
+```
+
+Commit the PDFs if you want the book to build without recompiling, or ignore
+them too and let CI regenerate them.
+
+## Licence
+
+MIT

sphinx_typst_render-0.2.0/README.md

@@ -0,0 +1,171 @@
+# sphinx-typst-render
+
+Compile [Typst](https://typst.app) sources during a Sphinx or Jupyter Book
+build. Each source becomes a PDF students can download, plus an optional inline
+preview image that follows the page theme.
+
+Typst ships inside the [`typst`](https://pypi.org/project/typst/) wheel as a
+statically linked extension module, so there is no `typst` CLI to install and no
+Rust toolchain on the build machine.
+
+## Install
+
+```bash
+pip install sphinx-typst-render
+```
+
+## Enable
+
+In a Jupyter Book `_config.yml`:
+
+```yaml
+sphinx:
+  extra_extensions:
+    - sphinx_typst_render
+```
+
+In a plain Sphinx `conf.py`:
+
+```python
+extensions = ["sphinx_typst_render"]
+```
+
+## Use
+
+````markdown
+```{typst} worksheets/week3.typ
+:label: Week 3 worksheet
+```
+````
+
+The block renders **nothing into the page**. It compiles `worksheets/week3.typ`
+and adds the resulting PDF to the theme's download menu, beside the page's own
+`.ipynb` and `.pdf` entries, under a heading you configure.
+
+Pass `:inline:` to also show a preview image and a download link in the body.
+
+### Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `:preview:` | `none`, or `svg` with `:inline:` | `svg`, `png`, or `none`. |
+| `:page:` | `1` | Which page to preview in a multi page document. |
+| `:height:` | unset | Height of the preview image, e.g. `420px`. |
+| `:alt:` | generated | Alt text for the preview image. |
+| `:label:` | generated | Text of the download link. |
+| `:ppi:` | `144` | Resolution of a `png` preview. |
+| `:class:` | none | Extra CSS classes on the wrapper. |
+| `:inline:` | off | Also show a preview and link in the page body. |
+| `:fillable:` | off | Add interactive form fields. See below. |
+
+### Configuration
+
+| Value | Default | Meaning |
+| --- | --- | --- |
+| `typst_render_preview` | `"svg"` | Default for `:preview:`. |
+| `typst_render_ppi` | `144.0` | Default for `:ppi:`. |
+| `typst_render_stage_field_library` | `True` | Stage `capture_field.typ` into the source root. |
+| `typst_render_source_label` | `"Source"` | Heading above the page's own downloads. |
+| `typst_render_downloads_label` | `"Worksheets"` | Heading above the rendered PDFs. |
+
+## The download menu
+
+Rendered PDFs are added to the download dropdown that sphinx-book-theme puts in
+the article header, so students find them where they already look for the page
+source. Two headings separate the groups, and both are configurable because
+what the page *is* differs per project:
+
+```yaml
+sphinx:
+  config:
+    typst_render_source_label: Manual      # or Chapter, Page, Book
+    typst_render_downloads_label: Worksheets
+```
+
+That renders as:
+
+```
+Manual
+  .ipynb
+  .pdf
+Worksheets
+  Organizer 1.1 (fillable)
+```
+
+Set either to an empty string to leave that group unlabelled.
+
+The headings are inserted by a small stylesheet and script shipped with this
+package. They are not built server side because the theme's button macro
+dispatches on a fixed set of item types and forces its own CSS class, so a
+non-link entry cannot be expressed through the `header_buttons` context.
+
+Without a theme that provides such a menu, the PDFs are still written and
+copied, and a warning names the page whose downloads are unreachable. Use
+`:inline:` in that case.
+
+## Why SVG previews
+
+With `:inline:`, an SVG preview is line art, so a theme that inverts diagrams for dark mode
+handles it correctly, and it stays sharp at any zoom. Use `:preview: png` for a
+worksheet that contains photographs, and pair it with whatever class your theme
+uses to opt out of inversion:
+
+````markdown
+```{typst} worksheets/week5.typ
+:preview: png
+:class: no-invert
+```
+````
+
+## Fillable PDFs
+
+Typst cannot emit interactive form fields on its own. Support is requested in
+[typst/typst#1765](https://github.com/typst/typst/issues/1765) and is still
+open. This package therefore delegates to
+[typst-fillable](https://github.com/carpe-diem/typst-fillable), which reads
+field geometry back out of the compiled document with `typst.query()`, draws a
+transparent AcroForm overlay with ReportLab, and merges it with pypdf.
+
+Mark fields in the Typst source with the helper, then add `:fillable:`:
+
+```typ
+#import "/_typst_lib/capture_field.typ": text_field, checkbox_field, textarea_field
+
+Measured $U_(i n)$: #text_field("u_in", width: 80pt)
+
+Did the output clip? #checkbox_field("clipped")
+
+Explain the discrepancy:
+#textarea_field("discussion", height: 60pt)
+```
+
+`capture_field.typ` is staged into `_typst_lib/` at the root of your Sphinx
+source directory on every build, so the import path above is stable wherever the
+worksheet lives. Set `typst_render_stage_field_library = False` to manage it
+yourself.
+
+Available helpers are `text_field`, `textarea_field`, `checkbox_field`, and
+`radio_field`, plus the lower level `capture_field`.
+
+## Caching
+
+Output is written beside the source and skipped when nothing relevant changed.
+The cache key covers the source, every other `.typ` file in the same folder, the
+staged helper, and the render options.
+
+Imports that reach outside the source folder are not tracked. Keep shared
+partials next to the worksheets that use them, or touch the importing file to
+force a rebuild.
+
+Add the generated artefacts to `.gitignore`:
+
+```gitignore
+*.typst-stamp
+```
+
+Commit the PDFs if you want the book to build without recompiling, or ignore
+them too and let CI regenerate them.
+
+## Licence
+
+MIT

sphinx_typst_render-0.2.0/pyproject.toml

@@ -0,0 +1,88 @@
+[project]
+name = "sphinx-typst-render"
+version = "0.2.0"
+description = "Render Typst sources into downloadable PDFs and inline previews in Sphinx and Jupyter Book."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "jupyter-book",
+    "sphinx",
+    "typst",
+    "pdf",
+    "forms",
+    "documentation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Sphinx",
+    "Framework :: Sphinx :: Extension",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Documentation :: Sphinx",
+    "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+    "sphinx>=7",
+    "typst>=0.15",
+    "typst-fillable>=0.0.1",
+]
+
+[[project.authors]]
+name = "NB-TUDelft"
+
+[[project.authors]]
+name = "K.Zabłocki (Zamkorus)"
+
+[project.urls]
+Homepage = "https://github.com/NB-TUDelft/sphinx-typst-render"
+Repository = "https://github.com/NB-TUDelft/sphinx-typst-render"
+Issues = "https://github.com/NB-TUDelft/sphinx-typst-render/issues"
+Changelog = "https://github.com/NB-TUDelft/sphinx-typst-render/releases"
+
+[project.scripts]
+sphinx-typst-render = "sphinx_typst_render:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "twine>=6.1",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sphinx_typst_render = [
+    "static/*.js",
+    "static/*.css",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.conda-recipe]
+noarch = true
+build-channels = ["conda-forge"]
+maintainers = [
+    "NB-TUDelft",
+    "Zamkorus",
+]
+test-imports = ["sphinx_typst_render"]
+extra-run = []
+
+[tool.conda-recipe.name-map]
+
+[tool.conda-recipe.requirement-overrides]
+
+[build-system]
+requires = ["uv_build>=0.12.14,<0.13.0"]
+build-backend = "uv_build"

sphinx_typst_render-0.2.0/pyproject.toml.orig

@@ -0,0 +1,89 @@
+[project]
+name = "sphinx-typst-render"
+version = "0.2.0"
+description = "Render Typst sources into downloadable PDFs and inline previews in Sphinx and Jupyter Book."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "NB-TUDelft" },
+    { name = "K.Zabłocki (Zamkorus)" },
+]
+keywords = ["jupyter-book", "sphinx", "typst", "pdf", "forms", "documentation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Sphinx",
+    "Framework :: Sphinx :: Extension",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Documentation :: Sphinx",
+    "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+    "sphinx>=7",
+    "typst>=0.15",
+    "typst-fillable>=0.0.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/NB-TUDelft/sphinx-typst-render"
+Repository = "https://github.com/NB-TUDelft/sphinx-typst-render"
+Issues = "https://github.com/NB-TUDelft/sphinx-typst-render/issues"
+Changelog = "https://github.com/NB-TUDelft/sphinx-typst-render/releases"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "twine>=6.1",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sphinx_typst_render = ["static/*.js", "static/*.css"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+
+[project.scripts]
+sphinx-typst-render = "sphinx_typst_render:main"
+
+[build-system]
+requires = ["uv_build>=0.12.14,<0.13.0"]
+build-backend = "uv_build"
+
+# Consumed by NB-TUDelft/actions/python-publish, which renders the conda
+# recipe from the metadata above so the conda package can never drift from the
+# PyPI one. Only what conda needs and pyproject cannot express lives here.
+#
+# Conda publishing is currently disabled in .github/workflows/publish.yml.
+# Two dependencies block it: typst (the Python binding) and typst-fillable are
+# both PyPI only. conda-forge ships a `typst` package, but that is the Rust CLI
+# and does not provide the importable module, so mapping to it would be wrong.
+[tool.conda-recipe]
+# The package itself is pure Python, so a single noarch build serves every
+# architecture and every Python >=3.10.
+noarch = true
+build-channels = ["conda-forge"]
+maintainers = ["NB-TUDelft", "Zamkorus"]
+test-imports = [
+    "sphinx_typst_render",
+]
+# PyPI project name -> conda-forge package name, where the two differ.
+name-map = {}
+# Escape hatch keyed by normalized PyPI name: replaces the auto-translated
+# spec outright. Use when a requirement carries an environment marker or
+# extras, which conda's dependency syntax cannot express.
+requirement-overrides = {}
+# Run-time requirements that apply only to the conda package.
+extra-run = []

sphinx_typst_render-0.2.0/src/sphinx_typst_render/__init__.py

@@ -0,0 +1,92 @@
+"""Render Typst sources into Sphinx and Jupyter Book output."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ._compile import RenderRequest, RenderResult, render, stage_field_library
+from ._directive import TypstDirective
+from ._downloads import (
+    add_download_buttons,
+    copy_downloads,
+    merge_info,
+    purge_doc,
+)
+
+__all__ = [
+    "RenderRequest",
+    "RenderResult",
+    "TypstDirective",
+    "render",
+    "setup",
+    "stage_field_library",
+]
+__version__ = "0.2.0"
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+#: Written into the output at build time, so the labels reach the browser as a
+#: file rather than an inline script. An inline script added through
+#: add_js_file(None, body=...) is emitted twice by sphinx-book-theme, which
+#: re-processes the asset list in its own html-page-context handler.
+LABELS_FILENAME = "typst-render-labels.js"
+
+
+def _install_assets(app) -> None:
+    """Register the dropdown header assets.
+
+    The labels file is generated here rather than at build-finished because
+    sphinx-book-theme fingerprints each asset by reading it while pages are
+    written. A file that does not exist yet at that point is dropped from the
+    page instead of being linked.
+    """
+    if getattr(app.builder, "format", None) != "html":
+        return
+
+    generated = Path(app.doctreedir).parent / "typst-render-static"
+    generated.mkdir(parents=True, exist_ok=True)
+    labels = {
+        "source": app.config.typst_render_source_label,
+        "downloads": app.config.typst_render_downloads_label,
+    }
+    (generated / LABELS_FILENAME).write_text(
+        f"window.typstRenderLabels = {json.dumps(labels)};\n"
+    )
+
+    app.config.html_static_path.append(str(STATIC_DIR))
+    app.config.html_static_path.append(str(generated))
+    # Labels first: typst-render.js reads the global this one defines.
+    app.add_js_file(LABELS_FILENAME)
+    app.add_js_file("typst-render.js")
+    app.add_css_file("typst-render.css")
+
+
+def setup(app):
+    app.add_config_value("typst_render_preview", "svg", "env")
+    app.add_config_value("typst_render_ppi", 144.0, "env")
+    app.add_config_value("typst_render_stage_field_library", True, "env")
+    # Headings inserted into the theme's download menu. The first names what
+    # the page itself is, which differs per project: a manual, a chapter, a
+    # page. An empty string leaves that group unlabelled.
+    # Offer the .typ source next to each rendered PDF.
+    app.add_config_value("typst_render_link_source", False, "env")
+    app.add_config_value("typst_render_source_label", "Source", "html")
+    app.add_config_value("typst_render_downloads_label", "Worksheets", "html")
+
+    app.add_directive("typst", TypstDirective)
+
+    app.connect("builder-inited", _install_assets)
+    app.connect("env-purge-doc", purge_doc)
+    app.connect("env-merge-info", merge_info)
+    # After sphinx-book-theme builds the download group at priority 501.
+    app.connect("html-page-context", add_download_buttons, priority=600)
+    app.connect("build-finished", copy_downloads)
+
+    return {
+        "version": __version__,
+        # Rendering writes files during the read phase, so parallel readers
+        # could race on the same output. Correctness over throughput here.
+        "parallel_read_safe": False,
+        "parallel_write_safe": True,
+    }

sphinx_typst_render-0.2.0/src/sphinx_typst_render/_compile.py

@@ -0,0 +1,206 @@
+"""Compile Typst sources to PDF and to inline preview images."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import typst
+
+#: Directory, relative to the Typst root, where the field helper is staged.
+LIB_DIRNAME = "_typst_lib"
+
+#: Directory, beside each source, holding generated output.
+OUT_DIRNAME = "_typst"
+LIB_FILENAME = "capture_field.typ"
+
+#: Bumped whenever the output layout changes, to invalidate stale caches.
+_CACHE_VERSION = 1
+
+
+@dataclass(frozen=True)
+class RenderRequest:
+    """Everything that determines the bytes of a render."""
+
+    source: Path
+    root: Path
+    preview: str = "svg"
+    fillable: bool = False
+    ppi: float | None = None
+    preview_page: int = 1
+
+
+@dataclass(frozen=True)
+class RenderResult:
+    """Paths written by :func:`render`."""
+
+    pdf: Path
+    preview: Path | None
+
+
+def stage_field_library(root: Path) -> Path | None:
+    """Copy typst-fillable's ``capture_field.typ`` into the Typst root.
+
+    Authors then import it by a stable root absolute path, which does not
+    change when a worksheet moves between week folders::
+
+        #import "/_typst_lib/capture_field.typ": text_field, checkbox_field
+
+    Returns the staged path, or ``None`` when typst-fillable is not installed.
+    """
+    try:
+        from importlib.resources import files
+
+        data = (files("typst_fillable") / "typst" / LIB_FILENAME).read_bytes()
+    except (ImportError, FileNotFoundError, ModuleNotFoundError):
+        return None
+
+    target = root / LIB_DIRNAME / LIB_FILENAME
+    target.parent.mkdir(parents=True, exist_ok=True)
+    # Only write when the content differs, so the mtime stays stable and the
+    # fingerprint below does not churn on every build.
+    if not target.is_file() or target.read_bytes() != data:
+        target.write_bytes(data)
+    return target
+
+
+def _options(request: RenderRequest) -> dict[str, object]:
+    try:
+        source_key = request.source.resolve().relative_to(request.root.resolve()).as_posix()
+    except ValueError:
+        source_key = request.source.name
+    return {
+        "version": _CACHE_VERSION,
+        # Output lives outside the source tree, so the key must identify the
+        # source. Two worksheets may share a stem in different week folders.
+        "source": source_key,
+        "preview": request.preview,
+        "fillable": request.fillable,
+        "ppi": request.ppi,
+        "page": request.preview_page,
+    }
+
+
+def _variant(request: RenderRequest) -> str:
+    """Short digest of the render options.
+
+    Two directives may point at one source with different options. Keying the
+    output directory on the options keeps them from overwriting each other,
+    while the file inside keeps the source stem so the download is named
+    ``week3.pdf`` rather than something hashed.
+    """
+    payload = json.dumps(_options(request), sort_keys=True).encode()
+    return hashlib.sha256(payload).hexdigest()[:8]
+
+
+def _fingerprint(request: RenderRequest) -> str:
+    """Hash everything that can change the output.
+
+    Covers the source, every other ``.typ`` file beside it (worksheets that
+    import shared partials keep them in the same folder), the staged helper,
+    and the render options. Imports reaching outside the source folder are not
+    tracked; touch the importing file to force a rebuild.
+    """
+    digest = hashlib.sha256()
+    digest.update(json.dumps(_options(request), sort_keys=True).encode())
+    for path in sorted(request.source.parent.glob("*.typ")):
+        digest.update(path.name.encode())
+        digest.update(path.read_bytes())
+
+    library = request.root / LIB_DIRNAME / LIB_FILENAME
+    if library.is_file():
+        digest.update(library.read_bytes())
+    return digest.hexdigest()
+
+
+def _add_form_fields(base: bytes, request: RenderRequest) -> bytes:
+    """Overlay interactive AcroForm fields onto an already compiled PDF.
+
+    Only the field extraction and the ReportLab overlay come from
+    typst-fillable. Its ``make_fillable()`` copies the whole Typst root into a
+    temp dir and then expects the template at the top of it, which breaks for
+    worksheets in subfolders, and its ``merge_with_overlay()`` merges page
+    content without carrying the widget annotations, so the result has an
+    /AcroForm whose /Fields point at nothing and no reader shows a field.
+
+    Cloning the overlay instead keeps the form dictionary and its widgets
+    intact in one document, and the Typst content is stamped underneath.
+    """
+    from io import BytesIO
+
+    from pypdf import PdfReader, PdfWriter
+    from typst_fillable import create_form_overlay, extract_field_metadata
+
+    fields = extract_field_metadata(request.source, root=request.root)
+    if not fields:
+        return base
+
+    reader = PdfReader(BytesIO(base))
+    first = reader.pages[0]
+    overlay = create_form_overlay(
+        fields=fields,
+        page_count=len(reader.pages),
+        page_size=(float(first.mediabox.width), float(first.mediabox.height)),
+    )
+
+    writer = PdfWriter(clone_from=overlay)
+    for index, page in enumerate(reader.pages):
+        if index < len(writer.pages):
+            writer.pages[index].merge_page(page, over=False)
+    # Ask the reader to build field appearances, so a blank field is visible.
+    writer.set_need_appearances_writer(True)
+
+    output = BytesIO()
+    writer.write(output)
+    return output.getvalue()
+
+
+def _compile_pdf(request: RenderRequest) -> bytes:
+    base = typst.compile(str(request.source), root=str(request.root), format="pdf")
+    if not request.fillable:
+        return base
+    return _add_form_fields(base, request)
+
+
+def _compile_preview(request: RenderRequest) -> bytes:
+    options: dict[str, object] = {"root": str(request.root), "format": request.preview}
+    if request.preview == "png":
+        options["ppi"] = request.ppi or 144.0
+
+    rendered = typst.compile(str(request.source), **options)
+    # A multi page document comes back as one bytes object per page.
+    if isinstance(rendered, list):
+        index = max(1, request.preview_page) - 1
+        if index >= len(rendered):
+            raise IndexError(
+                f"{request.source.name} has {len(rendered)} pages, "
+                f"cannot preview page {request.preview_page}"
+            )
+        return rendered[index]
+    return rendered
+
+
+def render(request: RenderRequest, basedir: Path) -> RenderResult:
+    """Compile ``request`` under ``basedir``, reusing cached output when valid.
+
+    Output lands in ``<basedir>/_typst/<options digest>/``.
+    """
+    outdir = basedir / OUT_DIRNAME / _variant(request)
+    outdir.mkdir(parents=True, exist_ok=True)
+    stem = request.source.stem
+    pdf = outdir / f"{stem}.pdf"
+    preview = None if request.preview == "none" else outdir / f"{stem}.{request.preview}"
+    stamp = outdir / f"{stem}.typst-stamp"
+
+    expected = _fingerprint(request)
+    if stamp.is_file() and stamp.read_text().strip() == expected:
+        if pdf.is_file() and (preview is None or preview.is_file()):
+            return RenderResult(pdf, preview)
+
+    pdf.write_bytes(_compile_pdf(request))
+    if preview is not None:
+        preview.write_bytes(_compile_preview(request))
+    stamp.write_text(expected)
+    return RenderResult(pdf, preview)

sphinx_typst_render-0.2.0/src/sphinx_typst_render/_directive.py

@@ -0,0 +1,150 @@
+"""The ``typst`` directive."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx import addnodes
+from sphinx.util.docutils import SphinxDirective
+
+from ._compile import RenderRequest, render, stage_field_library
+from ._downloads import register
+
+
+def _preview(argument: str) -> str:
+    return directives.choice(argument, ("svg", "png", "none"))
+
+
+def _yes_no(argument: str) -> str:
+    return directives.choice(argument, ("yes", "no"))
+
+
+class TypstDirective(SphinxDirective):
+    """Compile a Typst source and offer it as a download.
+
+    The block renders nothing into the page. The PDF is added to the theme's
+    download menu, next to the page's own source files. Pass ``:inline:`` to
+    also show a preview and a link in the body.
+
+    ::
+
+        ```{typst} worksheets/week3.typ
+        :label: Week 3 worksheet
+        :fillable:
+        ```
+    """
+
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    has_content = False
+    option_spec = {
+        "preview": _preview,
+        "fillable": directives.flag,
+        "inline": directives.flag,
+        "source": _yes_no,
+        "label": directives.unchanged,
+        "alt": directives.unchanged,
+        "height": directives.length_or_unitless,
+        "ppi": directives.positive_int,
+        "page": directives.positive_int,
+        "class": directives.class_option,
+    }
+
+    def run(self) -> list[nodes.Node]:
+        config = self.env.config
+        relative, absolute = self.env.relfn2path(self.arguments[0].strip())
+        source = Path(absolute)
+        if not source.is_file():
+            raise self.error(f"Typst source not found: {relative}")
+
+        # Rebuild the page whenever the source changes.
+        self.env.note_dependency(relative)
+
+        root = Path(self.env.srcdir)
+        if config.typst_render_stage_field_library:
+            stage_field_library(root)
+
+        inline = "inline" in self.options
+        # Without an inline block there is nothing to show a preview in, so do
+        # not spend a second Typst compile on one.
+        default_preview = config.typst_render_preview if inline else "none"
+
+        request = RenderRequest(
+            source=source,
+            root=root,
+            preview=self.options.get("preview", default_preview),
+            fillable="fillable" in self.options,
+            ppi=self.options.get("ppi", config.typst_render_ppi),
+            preview_page=self.options.get("page", 1),
+        )
+
+        # An inline preview has to be an image Sphinx can see, which means it
+        # must live under the source directory. With no inline block there is
+        # nothing to keep there, so the output goes to a build local cache and
+        # the author's folders stay clean.
+        basedir = (
+            source.parent
+            if inline
+            else Path(self.env.doctreedir).parent / "typst-build"
+        )
+
+        try:
+            result = render(request, basedir)
+        except Exception as error:
+            # A clean build is a hard requirement, so surface this as an error
+            # rather than a warning that scrolls past unnoticed.
+            raise self.error(f"Typst render failed for {relative}: {error}") from error
+
+        label = self.options.get("label") or result.pdf.stem
+        digest = result.pdf.parent.name
+        register(
+            self.env,
+            self.env.docname,
+            digest=digest,
+            path=result.pdf,
+            label=label,
+        )
+
+        want_source = self.options.get(
+            "source", "yes" if config.typst_render_link_source else "no"
+        )
+        if want_source == "yes":
+            register(
+                self.env,
+                self.env.docname,
+                digest=digest,
+                path=source,
+                label=f"{label} (source)",
+                icon="fas fa-file-code",
+            )
+
+        if not inline:
+            return []
+
+        container = nodes.container(
+            classes=["typst-render", *self.options.get("class", [])]
+        )
+
+        if result.preview is not None:
+            uri = "/" + result.preview.relative_to(root).as_posix()
+            image = nodes.image(uri=uri)
+            image["candidates"] = {"*": uri}
+            image["alt"] = self.options.get("alt", f"Preview of {source.name}")
+            if "height" in self.options:
+                image["height"] = self.options["height"]
+            container += image
+
+        reference = addnodes.download_reference(
+            "",
+            "",
+            reftarget="/" + result.pdf.relative_to(root).as_posix(),
+            refdoc=self.env.docname,
+            refexplicit=True,
+            refwarn=False,
+        )
+        reference += nodes.literal(label, label, classes=["xref", "download"])
+        container += nodes.paragraph("", "", reference, classes=["typst-download"])
+        return [container]

sphinx_typst_render-0.2.0/src/sphinx_typst_render/_downloads.py

@@ -0,0 +1,110 @@
+"""Put rendered PDFs into the theme's download menu instead of the page body."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from sphinx.util import logging
+
+LOGGER = logging.getLogger(__name__)
+
+#: Attribute on the build environment holding {docname: [entry, ...]}.
+ENV_KEY = "typst_render_downloads"
+
+#: Output subdirectory, below the HTML output root.
+URI_PREFIX = "_downloads/typst"
+
+#: Button label, which the theme turns into a "btn-<label>" class. The
+#: companion JavaScript uses that class to find our entries in the menu.
+BUTTON_LABEL = "typst-download"
+
+#: Label of the download group that sphinx-book-theme builds.
+THEME_GROUP_LABEL = "download-buttons"
+
+
+def _store(env) -> dict[str, list[dict]]:
+    if not hasattr(env, ENV_KEY):
+        setattr(env, ENV_KEY, {})
+    return getattr(env, ENV_KEY)
+
+
+def register(
+    env, docname: str, *, digest: str, path: Path, label: str, icon: str = "fas fa-file-pdf"
+) -> str:
+    """Record one download for ``docname`` and return its output relative URI."""
+    uri = f"{URI_PREFIX}/{digest}/{path.name}"
+    entries = _store(env).setdefault(docname, [])
+    # A page may hold several worksheets, but re-reading it must not duplicate.
+    for entry in entries:
+        if entry["uri"] == uri:
+            entry["label"] = label
+            return uri
+    entries.append({"uri": uri, "path": str(path), "label": label, "icon": icon})
+    return uri
+
+
+def purge_doc(app, env, docname: str) -> None:
+    _store(env).pop(docname, None)
+
+
+def merge_info(app, env, docnames, other) -> None:
+    _store(env).update(_store(other))
+
+
+def add_download_buttons(app, pagename, templatename, context, doctree) -> None:
+    """Append this page's worksheets to the theme's download dropdown.
+
+    Runs after sphinx-book-theme has built ``header_buttons`` (priority 501),
+    so the group already exists and we only extend it.
+    """
+    entries = _store(app.env).get(pagename)
+    if not entries:
+        return
+
+    group = next(
+        (
+            item
+            for item in context.get("header_buttons", [])
+            if item.get("type") == "group" and item.get("label") == THEME_GROUP_LABEL
+        ),
+        None,
+    )
+    if group is None:
+        LOGGER.warning(
+            "sphinx-typst-render: no download menu on %s, so %d worksheet(s) are "
+            "not reachable. The theme must provide one, as sphinx-book-theme does "
+            "with use_download_button enabled.",
+            pagename,
+            len(entries),
+            type="typst_render",
+        )
+        return
+
+    pathto = context["pathto"]
+    for entry in entries:
+        group["buttons"].append(
+            {
+                "type": "link",
+                "url": pathto(entry["uri"], 1),
+                "text": entry["label"],
+                "icon": entry.get("icon", "fas fa-file-pdf"),
+                "tooltip": entry["label"],
+                "label": BUTTON_LABEL,
+            }
+        )
+
+
+def copy_downloads(app, exception) -> None:
+    """Copy the rendered PDFs into the output tree."""
+    if exception is not None or getattr(app.builder, "format", None) != "html":
+        return
+    outdir = Path(app.builder.outdir)
+    for entries in _store(app.env).values():
+        for entry in entries:
+            source = Path(entry["path"])
+            if not source.is_file():
+                continue
+            destination = outdir / entry["uri"]
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(source, destination)

sphinx_typst_render-0.2.0/src/sphinx_typst_render/static/typst-render.css

@@ -0,0 +1,22 @@
+/* Section headings inside the theme's download dropdown.
+   The bundled Bootstrap subset does not style .dropdown-header, so do it here.
+   Colours come from pydata-sphinx-theme variables, which follow the light and
+   dark theme toggle, with plain fallbacks for other themes. */
+.dropdown-download-buttons .dropdown-menu .dropdown-header {
+  display: block;
+  margin: 0;
+  padding: 0.35rem 1rem 0.2rem;
+  font-size: 0.72rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  white-space: nowrap;
+  color: var(--pst-color-text-muted, #6c757d);
+}
+
+/* Separate the second and later groups from the one above. */
+.dropdown-download-buttons .dropdown-menu .dropdown-header:not(:first-child) {
+  margin-top: 0.3rem;
+  padding-top: 0.45rem;
+  border-top: 1px solid var(--pst-color-border, #d1d5da);
+}

sphinx_typst_render-0.2.0/src/sphinx_typst_render/static/typst-render.js

@@ -0,0 +1,49 @@
+// Insert section headers into the theme's download dropdown, so the page's own
+// source files and the worksheets rendered by sphinx-typst-render read as two
+// labelled groups rather than one undifferentiated list.
+//
+// The headers are added here rather than server side because the theme macro
+// dispatches on a fixed set of button types and forces its own item class, so
+// a non-link entry cannot be expressed through the header_buttons context.
+(function () {
+  "use strict";
+
+  var OURS = ".btn-typst-download";
+  var MARK = "data-typst-headed";
+
+  function addHeader(menu, before, text) {
+    if (!text || !before) return;
+    var item = document.createElement("li");
+    var heading = document.createElement("h6");
+    heading.className = "dropdown-header";
+    heading.textContent = text;
+    item.appendChild(heading);
+    menu.insertBefore(item, before);
+  }
+
+  function decorate() {
+    var labels = window.typstRenderLabels || {};
+    var menus = document.querySelectorAll(".dropdown-download-buttons ul.dropdown-menu");
+
+    Array.prototype.forEach.call(menus, function (menu) {
+      if (menu.hasAttribute(MARK)) return;
+
+      var items = Array.prototype.slice.call(menu.children);
+      var ours = items.filter(function (li) { return li.querySelector(OURS); });
+      // Nothing of ours on this page means nothing to separate.
+      if (!ours.length) return;
+
+      var theirs = items.filter(function (li) { return !li.querySelector(OURS); });
+      menu.setAttribute(MARK, "");
+      // Insert the lower header first so the reference node stays valid.
+      addHeader(menu, ours[0], labels.downloads);
+      addHeader(menu, theirs[0], labels.source);
+    });
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", decorate);
+  } else {
+    decorate();
+  }
+})();