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

[bestbeforetoday]

Is there output we can look at where you have run this on your fork so we don't have to manually stand up and run the doc build process to review it?

[nielspardon]

Is there output we can look at where you have run this on your fork so we don't have to manually stand up and run the doc build process to review it?

I don't have this deployed. Running it locally is straightforward if you have pixi installed:

pixi run docs-serve

[bestbeforetoday]

It would give some confidence that the GitHub Actions workflows are good if they were run in a fork before merging here, although I guess it should not break any other part of the build.

I suspect some repository settings might need to change to allow the workflow to run successfully and published documentation to be viewable. Any changes can be identified and documented by testing in a fork.

[nielspardon]

It would give some confidence that the GitHub Actions workflows are good if they were run in a fork before merging here, although I guess it should not break any other part of the build.

I suspect some repository settings might need to change to allow the workflow to run successfully and published documentation to be viewable. Any changes can be identified and documented by testing in a fork.

I have everything prepared. I can not finalize the repo settings without this being merged and run.