Docs/mkdocs material rtd

[nseetim]

Summary

Adds a MkDocs Material documentation site (similar in toolchain to FastAPI/Pydantic), wires Read the Docs to build from mkdocs.yml, and runs a strict MkDocs build in CI so broken docs fail PR checks.

Motivation

• README/PyPI are great for a snapshot but don’t scale for guides, structured navigation, or generated API docs.
• The repo already pointed at Read the Docs and used Sphinx with minimal content; MkDocs gives a clearer path for contributors and users.

What’s included

• mkdocs.yml — Material theme, search, strict mode, docs_dir: docs/mkdocs.
• docs/mkdocs/ — Home, Getting started, API reference (mkdocstrings), FastAPI, Contributing.
• [project.optional-dependencies] docs — mkdocs-material, mkdocstrings[python].
• docs-build — uv sync --extra docs + mkdocs build --strict.
• .readthedocs.yaml — switched from Sphinx to MkDocs, installs with pip install .[docs].
• .github/workflows/python-app.yml — uv sync --extra docs + uv run ./docs-build after typecheck.
• README.md — prominent docs URL + how to run mkdocs serve / ./docs-build locally.

Notes for maintainers

• Read the Docs project settings may need the documentation type set to MkDocs (if it was still Sphinx).
• PDF builds were dropped from .readthedocs.yaml (they were tied to Sphinx). HTML-only is typical for MkDocs; PDF can be revisited separately if desired.
• Legacy docs/conf.py / Sphinx scaffold remains in the repo for reference; the canonical published build is MkDocs per Contributing.

Test plan

• uv sync --extra docs
• uv run ./docs-build (strict)
• pytest (existing suite)

---