docs: migrate from Sphinx to MkDocs + Material for MkDocs

Replace the Sphinx toolchain (sphinx, sphinx-autoapi, sphinx-rtd-theme,
myst-parser) with MkDocs + Material + mkdocstrings. Read the Docs keeps
hosting the site.

- pyproject: swap the `docs` dependency group; ignore two pymdown-extensions
  advisories only fixed for Python >=3.10 (docs-only dep, same rationale as
  the existing uv.audit ignores)
- mkdocs.yaml: new config -- Material theme, mkdocstrings python handler,
  nav, site_dir: var/html-docs, toc_depth "2-6"
- docs/: drop conf.py, index.rst and the committed sphinx-autoapi
  docs/modules/ tree; add index.md, configuration.md and hand-written
  reference/*.md mkdocstrings stubs for the five modules
- docs/readme.md: absolute raw-GitHub image URL and an RTD link so the PyPI
  long description renders (relative paths only resolve on GitHub)
- src: rewrite the reStructuredText-flavoured module/function docstrings in
  __init__.py and status.py as Markdown so mkdocstrings renders them
- .readthedocs.yaml: `mkdocs:` key instead of `sphinx:`, drop pdf output
  (Sphinx-only on RTD), keep htmlzip
- justfile: .just/sphinx.justfile -> .just/mkdocs.justfile

Dropped mkdocs-gen-files / mkdocs-literate-nav / mkdocs-section-index: they
now depend on `properdocs`, a MkDocs fork that pulls a second site generator
into the tree and injects promotional build output. Five modules do not need
generated nav.

Author: woutervh

.just/mkdocs.justfile

@@ -0,0 +1,28 @@
+# MkDocs + Material -- see ../mkdocs.yaml
+
+
+# show which mkdocs is used
+[group: 'mkdocs']
+mkdocs-which:
+    @ which mkdocs
+
+
+# build the static site into var/html-docs (strict: fail on broken refs/links)
+[group: 'mkdocs']
+mkdocs-docs:
+    mkdocs build --strict
+    @echo
+    @echo "Build finished -> var/html-docs (see site_dir in ../mkdocs.yaml)"
+
+
+# Extra args pass through, e.g.
+#   just mkdocs-serve -a 0.0.0.0:8000   # bind all interfaces (then browse localhost, NOT 0.0.0.0)
+#   just mkdocs-serve --no-strict
+# live-reloading preview on http://127.0.0.1:8000/ (or http://localhost:8000/ from a WSL2 browser)
+[group: 'mkdocs']
+mkdocs-serve *args:
+    mkdocs serve {{ args }}
+
+
+# alias for mkdocs-docs
+alias docs := mkdocs-docs

.just/sphinx.justfile

@@ -22,10 +22,8 @@ build:
 
 formats:
     - htmlzip
-    - pdf
-    # - epub
-    # - all
+    # pdf/epub are Sphinx-only on Read the Docs and not available for MkDocs builds.
 
-sphinx:
-    configuration: docs/conf.py
-    fail_on_warning: false # true is too strict
+mkdocs:
+    configuration: mkdocs.yaml
+    fail_on_warning: false # Material for MkDocs prints an (unsuppressable) MkDocs-2.0 banner

.readthedocs.yaml

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 ## 1.0.7 (unreleased)
 
+- Migrate the documentation from Sphinx to MkDocs + Material for MkDocs. The API
+  reference is now generated by `mkdocstrings` (Python handler) instead of
+  `sphinx-autoapi`; `docs/conf.py`, `docs/index.rst` and the committed
+  `docs/modules/` tree are gone, replaced by `mkdocs.yaml`, `docs/index.md` and
+  `docs/reference/*.md`. Read the Docs keeps hosting the site (`htmlzip` output
+  retained; `pdf` dropped -- Sphinx-only on RTD). Module/function docstrings that
+  used reStructuredText markup (`.. code-block::`, `:func:` / `:class:` roles)
+  were rewritten in Markdown so they render correctly. Adds a `docs/configuration.md`
+  page documenting the `AUTOREAD_DOTENV_PATH` and `AUTOREAD_ENFORCE_DOTENV`
+  environment-variables, which must be set outside `.env`.
+
 - Narrow the blanket `except OSError` in `get_dotenv_path()`. `PermissionError` from
   `is_file()` itself (the documented Python < 3.12 case of an unreadable parent directory)
   still returns the path optimistically and defers to `load_dotenv()`. Any other `OSError`