docs: migrate documentation from MkDocs to Sphinx + MyST

[prateek-dagar]

Why this pull request is being made

Addresses #80.

In light of the ongoing maintenance uncertainties in the MkDocs/MkDocs-Material ecosystem, this PR permanently migrates the documentation from MkDocs to Sphinx + MyST with the sphinx-immaterial theme.

Key Changes

• Parser & Engine: Replaced mkdocs with Sphinx and myst-parser, preserving all existing .md files without rewriting to ReST.
• Theme & Navigation Parity: Configured sphinx-immaterial with color palettes, navigation features, and version_json: 'versions.json' to maintain seamless compatibility with historical versions on gh-pages.
• API Reference: Transitioned from the mkdocstrings generator script to native Sphinx autodoc / autosummary stubs under docs/reference/.
• Tooling & CI:
  • Added [testenv:docs] to tox.ini (sphinx-build -b html docs site/_build/html).
  • Added automated docs verification job to .github/workflows/test-suite.yml.
  • Updated pyproject.toml dev dependency group with required Sphinx packages and removed obsolete MkDocs packages.
  • Cleaned up obsolete mkdocs.yml and scripts/gen_ref_nav.py.

Migration Tooling & Note

As part of tackling this transition, I also built an open-source migration tool, sphinx-mkdocs-migrate, specifically to automate deterministic AST conversions from MkDocs to Sphinx + MyST and scaffold sphinx-immaterial. I used it to perform this migration, and if you get some time, I would really love to get your thoughts and feedback on it!

How this was tested

• Docs Build: Verified with uvx tox -e docs:
  • All 18 HTML pages and API reference stubs built cleanly into site/_build/html with 0 directive/document warnings.
  • Full sitemap (sitemap.xml) and search index generated.
• Linters & Tests: Ran uvx tox -e lint (black, validate-pyproject, pylint 10/10, mypy) — all passing.

[nhairs]

Hi @prateek-dagar,

Thanks for putting this together. You actually beat me by a few hours in responding to your comment on #80 😅

This is really useful to understand what moving to Sphinx would look like. Which leads me to the decision that I don't think I want to move to Sphinx, and instead pin versions / move to the maintained alternatives - at least for the short term.

I'll expand my rationale on #80