docs: switch from Sphinx to MkDocs (Material), keep ReadTheDocs support

[andre-merzky]

Switches the documentation stack from Sphinx to MkDocs, mirroring the sibling repos (rhapsody, radical.asyncflow) so the three stay in sync on theme, config, and API-reference tooling.

What changed

• mkdocs.yml at the repo root — Material theme with rhapsody's exact feature/palette/extensions config (blue grey/teal, 3-state light/dark/auto toggle, same markdown_extensions set).
• All 11 .rst pages converted to Markdown under docs/ (flattened from docs/source/); the two existing .md pages moved over.
  • module_radical.orbit.rst → prose kept as architecture.md; its automodule dump is replaced by the generated api/ tree.
  • plugin_api / runtime_embedding autodoc directives → mkdocstrings ::: blocks (same curated member selections).
  • Tutorial literalinclude :pyobject: → pymdownx.snippets section markers in plugin_math.py / test_plugin_math.py, so the tutorial keeps rendering live source.
• Auto-generated per-module API reference — docs/gen_ref_pages.py (gen-files + literate-nav + section-index + mkdocstrings), same pattern and options as rhapsody, flat under api/, private _* modules skipped.
• ReadTheDocs stays supported — .readthedocs.yaml now uses the native mkdocs: build key and installs pip install .[docs]; setup.py's docs extra keeps mirroring docs/requirements.txt unchanged, so pip install .[docs] / [dev] stay in sync.
• Sphinx remnants removed — conf.py (2012 vintage), docs/Makefile, the armstrong theme, _static CSS, toctree/genindex pages; repo-wide sweep found one stale reference (plugin_math.py docstring), fixed.
• Docstring fixes surfaced by griffe — return annotations on the queue_info listing methods, psij Raises: format, missing param types, one indentation fix. These make the rendered API pages parse correctly.

Heads-up: MkDocs ecosystem upheaval (why the <2.0 pin)

MkDocs 1.x is unmaintained and its PyPI ownership changed hands in March 2026; an incompatible "MkDocs 2.0" has been announced, and a former maintainer launched the drop-in fork ProperDocs (which the gen-files/literate-nav/section-index plugins now pull in as a dependency — expect it in the RTD build env). This PR deliberately stays on mkdocs>=1.5.0,<2.0 — the pin prevents a hostile/incompatible 2.0 from ever breaking the RTD build. Whether to migrate to ProperDocs later is an ecosystem-level call best made together with rhapsody/asyncflow (which have the same exposure and currently no upper bound — worth syncing the <2.0 guard back to them). Context: Material's analysis, ProperDocs announcement, The Slow Collapse of MkDocs.

Verification

• mkdocs build --strict — clean, zero warnings (was 116 on the first pass; duplicate-anchor and docstring issues all resolved).
• PYTHONPATH=src pytest tests/unittests/ -q — 1028 passed, 3 environment skips (quickjs / radical.pilot, pre-existing).
• flake8 clean on all touched files.
• Rendered site spot-checked: tutorial code snippets, curated plugin API page (738 doc objects), generated module pages, admonitions, tables.

Post-merge

• RTD project settings need no change (.readthedocs.yaml drives the builder); the first RTD build after merge confirms the switch.
• docs/slides/ untouched.

🤖 Generated with Claude Code