Skip to content

Building the docs#

The documentation is built with MkDocs and the Material theme, with API reference auto-generated by mkdocstrings from the source docstrings. Versioned deploys are handled by mike.

Build locally#

pixi run docs-build   # one-shot build into ./site
pixi run docs-serve   # live-reloading dev server

How pages are produced#

  • Markdown pages live under docs/.
  • The API reference at docs/reference/api/ is not committed — it's generated at build time by docs/scripts/gen_ref_pages.py from every non-underscore-prefixed module in presto/. To change which modules are included or how the auto-pages are rendered, edit that script.
  • Example notebooks under examples/ are surfaced via mkdocs-jupyter. Notebooks are not executed at build time; commit them with pre-executed outputs.

Deploying#

CI deploys the docs automatically via .github/workflows/docs.yaml when a release tag is pushed. To deploy manually:

pixi run docs-deploy   # wraps `mike deploy --push --update-aliases $VERSION`

mike writes versioned snapshots to the gh-pages branch; old tagged versions stay reachable at their original URLs.