mkdocs 2.0 and community issues

[nhairs]

It appears mkdocs and mkdocs-material are having community issues leading to the projects to become unstable/unmaintained: https://fpgmaas.com/blog/collapse-of-mkdocs/

For now we should make sure to pin mkdocs<2 so that things can continue to build, but we should consider moving to a different tool to generate the docs.

Going forward it looks like our options are:

• Move to properdocs + mkdocs-materialx which are maintained drop-in replacements.
• Move to Zensical which is built by the mkdocs-material team.
• Move to Sphinx with some kind of markdown parser and a material theme

[prateek-dagar]

Hi @nhairs,

Pinning mkdocs<2 makes sense for the short term, but for a permanent fix, Sphinx is definitely the most stable and future-proof choice:

• Zero ecosystem risk: Battle-tested and backed by the PSF—avoids the maintenance uncertainties of recent forks.
• Keep Markdown as-is: Using myst-parser, we can keep all existing .md files without rewriting to ReST.
• Native Python docs: autodoc + intersphinx natively link docstrings and Python standard library types (logging.Formatter, etc.).
• Modern UI: We can use sphinx-book-theme or sphinx-immaterial for a clean, responsive layout with dark mode.
• Zero URL breakage: Continues building directly to GitHub Pages via Actions.

I'd be happy to take this on and submit a complete PR (Sphinx setup, pyproject.toml, tox, and GitHub Actions).

What do you think? If you have a preferred theme (e.g., Book vs. Immaterial), let me know and I can get started!