docs: add versioned documentation site built with Zensical

[nielspardon]

What

Adds a user-facing documentation site under docs/, built with
Zensical (from the Material for MkDocs team) and published
as multi-version docs via the Zensical-compatible fork of
mike. There was previously no user-facing
guide — users learned the API from the READMEs and tests. Tooling and layout
mirror substrait-io/substrait-python so the two repositories stay consistent.

Contents

• docs/ — comprehensive guides segmented into the four modules:
  • Core — building plans (the SubstraitBuilder DSL), types, expressions,
    relations, serialization, extended expressions, function & type extensions.
  • Isthmus — SQL ⇄ Substrait, SQL expressions, Substrait → SQL / Calcite,
    the type system, customization, and supported SQL.
  • Isthmus CLI — install/build, usage (all flags), and worked examples.
  • Spark — compatibility & per-variant dependencies, producing and consuming
    plans, supported features, and the end-to-end example.
  • Plus a landing page and getting-started. Every code sample is grounded in the
    real APIs and tests rather than invented.
• zensical.toml — Material theme, site_url, explicit nav, and the mike
  version provider (renders the version selector).
• pixi.toml — a docs environment (zensical + the mike fork) with
  docs-build / docs-serve tasks. Python and the docs dependencies are managed
  with pixi.
• CI — .github/workflows/docs.yml build-checks the docs on every PR and push
  to main. .github/workflows/docs-deploy.yml publishes versioned docs to the
  gh-pages branch via mike on release tags (the bare X.Y.Z tag publishes the
  minor series X.Y and updates the latest alias), and can be run manually via
  workflow_dispatch.
• readme.md / CONTRIBUTING.md — a Documentation section (hosted URL, local
  preview/build, authoring guidelines).

Building locally

pixi run docs-serve   # live-reloading preview at http://localhost:8000
pixi run docs-build   # build the static site into ./site

Enabling GitHub Pages (one-time, after merge)

Versioned publishing needs the gh-pages branch to exist before Pages can point
at it:

1. Actions → Deploy documentation → Run workflow (creates gh-pages), or
   let the next release tag create it.
2. Settings → Pages → Source → Deploy from a branch → gh-pages / (root).
3. From then on, each release tag publishes that minor series and updates the
   latest alias. Adjust site_url in zensical.toml if the site is served from
   a custom domain.

Verification

• pixi run docs-build completes with no issues (Zensical includes link validation).
• Dry-ran mike deploy + mike set-default locally (no push): correct gh-pages
  layout (<version>/, latest/, .nojekyll, versions.json, root redirect).
• Draft PR: the deploy workflow is intentionally not run against the canonical repo
  until GitHub Pages is enabled.

🤖 Generated with AI

[mbwhite]

will we be able to include the documentation from the JavaDoc as well?

[nielspardon]

will we be able to include the documentation from the JavaDoc as well?

probably something we can investigate in a follow-up. technically, it is included via links but need to check what Zensical currently supports in terms of embedding it