README.md

Website

The website is a Quarto project in this directory. To render it you need quarto, R, and the Python docs environment (uv sync --group docs). From the repository root:

cd docs

# Regenerate the API reference from the Python docstrings.
uv run quartodoc build

# Restore the R environment used by the benchmark document.
Rscript -e 'if (!requireNamespace("renv", quietly = TRUE)) install.packages("renv"); renv::load("."); renv::restore(prompt = FALSE)'
quarto render # or quarto render <document>.qmd

The website is then rendered into docs/_site. Quarto runs every .qmd in its own session, so any document with R or Python chunks needs the activation chunk that benchmark.qmd starts with (renv::load() + use_virtualenv()). Documents with no executable code (such as the generated reference/ pages) don't need it.

The API reference under docs/reference/ is generated by quartodoc from the Python docstrings. It is not tracked by git (like docs/objects.json and _quartodoc-sidebar.yml); run uv run quartodoc build every time before rendering or publishing, so the generated pages, the inventory, and the sidebar match the source docstrings.

Cross-references between pages are resolved by the vendored interlinks.lua filter, which reads the generated objects.json inventory. In a docstring you can link an object with either `ObjectName` (autolink, using the short-name aliases in _quarto.yml) or [text](`qte.module.ObjectName`). To preview only the API reference without executing the benchmark, run uv run quartodoc build followed by quarto preview reference/index.qmd.

The left navigation menu is generated by the same command into _quartodoc-sidebar.yml and merged into the project through metadata-files in _quarto.yml. Both that file and the generated reference pages are untracked and must be regenerated before any render.

Rendering tweaks that quartodoc cannot express in config live in docs/renderer.py (wired up with renderer.style: renderer.py); the config in _quarto.yml only supplies the other renderer options.

Publishing

The rendered site is published to the gh-pages branch; the docs/_site build output itself is not tracked. quarto publish renders and pushes in one step; regenerate the API reference first so the published site is up to date:

cd docs
uv run quartodoc build
PREK_ALLOW_NO_CONFIG=1 quarto publish gh-pages

Add --no-render to push an existing docs/_site without rendering again.

quarto publish commits the built site from a temporary worktree, which is a checkout of gh-pages and therefore has no prek.toml; the PREK_ALLOW_NO_CONFIG=1 prefix stops the prek git hooks from erroring out there (alternatively run prek install --allow-missing-config once).

The first time, enable Pages once under Settings → Pages → Deploy from a branch → gh-pages / (root). Because the local build is what gets pushed, publish from the machine whose environment should appear in the benchmark — the Environment section reflects the rendering machine.