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

[prateek-dagar]

Hi @nhairs,

Thanks for reviewing! Honestly, it was a lot of fun to work on this migration experiment—it actually led to me building and publishing my very first Python package (sphinx-mkdocs-migrate), so I'm really glad I could help provide a concrete example to make your decision easier! 😄

I totally understand your decision. While doing the migration, I noticed that while Sphinx is powerful, trying to get it to exactly mimic MkDocs (like generating the clean parameter description tables from mkdocstrings) requires a lot of custom handling and significantly more effort than the out-of-the-box MkDocs experience.

If you ever decide you want to fully migrate in the future, please let me know—I would be more than happy to work on it again! In the meantime, if you'd like, I can gladly help work on the proposed short-term solution of pinning the versions or migrating to the actively maintained MkDocs alternatives on Issue #80.

I'll go ahead and close this PR to keep your queue clean. Thanks again!

[nhairs]

Thanks for your understanding and positive attitude 😃