📝 docs: restructure following Diataxis framework (#448)

The documentation previously mixed learning material, task recipes,
background explanations, and API reference in the same files. A new user
trying to get started would land in `usage.rst` alongside advanced
platform conventions and real-world project examples, making it hard to
follow a clear learning path. Similarly, someone looking for a quick
recipe had to skim past explanatory prose to find the code they needed.

This restructures the docs into the four quadrants of the [Diataxis
framework](https://diataxis.fr/): a step-by-step `tutorial.rst` for
newcomers, a recipe-focused `howto.rst` for practitioners, an
`explanation.rst` gathering all platform conventions and design
rationale, and the existing `api.rst`/`platforms.rst` as pure reference.
The tutorial uses first-person plural and imperative steps with
verifiable output at each stage. The how-to guides are action-first with
minimal explanation, including new recipes for config merging via
`iter_config_paths`, testing with mocks, and environment variable
overrides. Platform convention prose that was duplicated between
`platforms.rst` and `howto.rst` now lives in one place in
`explanation.rst`.

Beyond the restructure, this adds several Sphinx extensions
(`sphinx-copybutton`, `sphinx-design`, `sphinx-sitemap`,
`sphinxcontrib-mermaid`, `sphinxext-opengraph`) and a `docstrfmt`
pre-commit hook for consistent RST and docstring formatting. The ruff
config is adjusted to defer to `docstrfmt` for docstring style (`D213`
ignored, `E501` ignored in favor of formatters). The `api.rst` now
documents the `iter_*` methods and the `AppDirs` backwards-compatibility
alias. The release workflow script is updated to match the new RST
heading style used by `docstrfmt`.

Author: gaborbernat

.github/workflows/release.yaml

@@ -80,12 +80,12 @@ jobs:
           fi
           git config user.name "${{ github.actor }}"
           git config user.email "${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com"
-          header="$VERSION ($(date -u +%Y-%m-%d))"
-          separator=$(printf '%0.s-' $(seq 1 ${#header}))
+          header=" $VERSION ($(date -u +%Y-%m-%d))"
+          separator=$(printf '%0.s*' $(seq 1 ${#header}))
           {
-            head -2 docs/changelog.rst
-            printf '%s\n%s\n%s\n\n' "$header" "$separator" "$CHANGELOG"
-            tail -n +3 docs/changelog.rst
+            head -4 docs/changelog.rst
+            printf '%s\n%s\n%s\n%s\n\n' "$separator" "$header" "$separator" "$CHANGELOG"
+            tail -n +5 docs/changelog.rst
           } > docs/changelog.tmp
           mv docs/changelog.tmp docs/changelog.rst
           git add docs/changelog.rst

.pre-commit-config.yaml

@@ -42,6 +42,12 @@ repos:
         additional_dependencies:
           - mdformat-gfm
           - mdformat-ruff
+  - repo: https://github.com/LilSpazJoekp/docstrfmt
+    rev: v2.0.2
+    hooks:
+      - id: docstrfmt
+        args: ["-l", "120"]
+        additional_dependencies: ["sphinx>=9.1"]
   - repo: meta
     hooks:
       - id: check-hooks-apply