build(docs): update Sphinx Stack to 2.0

[lengau]

Migrate documentation tooling to Sphinx Stack 2.0:

• Move documentation development and lint tooling from .sphinx to docs/_dev.
• Update docs Makefile with Sphinx Stack 2.0 targets (vale, pa11y, etc).
• Update conf.py for Sphinx Stack 2.0 (sitemap, llms.txt, canonical theme).
• Add explanation/documentation page.
• Add docs/requirements.txt.
• Adopt docs-sphinx-stack dependency group in pyproject.toml and regenerate lockfile.
• Ignore docs/_dev in .prettierignore.

Provenance

• Upstreamed from Starbase commit fafd1fc
• Originating Starbase PR: canonical/starbase#537.

Note: This is a preparation PR opened in advance of the Starbase synchronization merge.

[Copilot]

🟡 Changes recommended

Critical Read the Docs and dependency-lock issues, along with failing Make targets, remain unresolved.

8 open findings

• Docs build ignores the Read the Docs output directory · New
• Trailing backslash breaks pdf-prep-force · New
• uv.lock resolves canonical-sphinx outside the required version range · New
• PA11Y_CMD causes redundant npm installations · New
• Vale failures are masked by the vocabulary restore command · New
• Custom Sphinx templates are not configured · New
• Documentation references nonexistent docs-setup target · New
• Documentation references nonexistent docs-lint target · New

What changed in this PR

Migrates documentation tooling to Sphinx Stack 2.0, including updated dependencies, build targets, configuration, templates, and documentation guidance.

Changes:

• Moves development tooling into docs/_dev.
• Adds Sphinx Stack dependencies and documentation requirements.
• Updates Make targets, Sphinx configuration, templates, and Read the Docs setup.
• Adds documentation process guidance and linting/accessibility tooling.

File	Summary
uv.lock	Updates documentation dependency resolution.
pyproject.toml	Adds the Sphinx Stack dependency group.
docs/​requirements.txt	Defines standalone documentation dependencies.
docs/​README.md	Documents documentation tooling workflows.
docs/​Makefile	Adds build, lint, Vale, and accessibility targets.
docs/​index.rst	Updates documentation navigation.
docs/​explanation/​index.rst	Adds the explanation page to navigation.
docs/​explanation/​documentation.rst	Adds documentation guidance.
docs/​conf.py	Updates Sphinx Stack configuration.
docs/​.gitignore	Ignores generated tooling files.
docs/​.custom_wordlist.txt	Expands documentation vocabulary.
docs/​_templates/​header.html	Adds the custom header template.
docs/​_templates/​footer.html	Adds the custom footer template.
docs/​_dev/​version	Records Sphinx Stack version 2.0.
docs/​_dev/​update_sp.py	Adds Sphinx Stack update tooling.
docs/​_dev/​pa11y.json	Configures accessibility checks.
docs/​_dev/​get_vale_conf.py	Fetches Vale configuration.
docs/​_dev/​.pymarkdown.json	Configures Markdown linting.
docs/​_dev/​.pre-commit-config.yaml	Defines documentation hooks.
.readthedocs.yaml	Configures the Read the Docs environment and build.

🧠 Review effort: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jahn-junior]

A few minor things, but no need for another review from me. Thanks!