chore(maintenance): pin Python 3.12 across the docs toolchain

[svozza]

Summary

npm run docs:local:setup used whatever python3 the host had, while the docs requirements need Python 3.10 or newer and CI runs 3.12. On an older interpreter the install failed with an opaque pip resolution error, and nothing in the repo recorded the requirement. The Docker path had drifted too: its base image ships Python 3.11, and its exact apk pin for Node no longer exists in the Alpine repository, so npm run docs:docker:build fails on main today. This PR pins the interpreter once, in docs/.python-version, and makes CI, the local script, the Docker image and the contributor docs all follow it.

Changes

• Add docs/.python-version pinning 3.12. It lives next to the requirements so that pyenv, uv and mise apply it only to the docs toolchain, not to every Python invocation in the checkout.
• reusable_publish_docs.yml: setup-python reads the pin through python-version-file instead of a hardcoded version, and caches pip downloads keyed on docs/requirements.txt, matching the cache: npm on the sibling step.
• docs:local:setup becomes python$(cut -d. -f1,2 docs/.python-version) -m venv --clear .venv && .venv/bin/pip install --require-hashes -r docs/requirements.txt, deriving the interpreter name from the pin's major and minor so a patch-level value in the file cannot break it. A PYTHON environment variable overrides the executable for setups that expose the interpreter under another name, such as conda, and the contributor pages say so. A host without that interpreter fails immediately with "command not found" instead of a misleading resolution error; --clear stops a stale venv keeping its old interpreter; --require-hashes gives local installs the same integrity check CI already applies.
• docs/Dockerfile: base on the digest-pinned official python:3.12-alpine image instead of squidfunk/mkdocs-material, and recreate what that image provided: git for the revision-date plugin, Node for TypeDoc, tini as init, the /docs workdir, the mkdocs serve entrypoint, and safe.directory for the mounted checkout. The Node apk pin is dropped; the image digest already fixes the Alpine release, and the exact package pin was what broke the build. pip installs with --no-cache-dir so the wheel cache is not baked into the image.
• .github/dependabot.yml: the docker updater ignores minor and major bumps of the python image so it refreshes the digest without moving the tag away from docs/.python-version.
• docs:local:api is plain typedoc, so typedoc.json's entryPoints apply instead of a positional . that hits the walk-root problem below.
• mkdocs.yml: the typedoc plugin's source is packages/* instead of .. In packages mode TypeDoc walks from the parent of the entry point, and for a repo mounted at /docs that parent is /, where its path handling matches nothing. packages/* gives it a walk root of packages, matches the entryPoints in typedoc.json, and documents the same fourteen packages.
• CONTRIBUTING.md and docs/contributing/setup.md name the pin file as the prerequisite for the non-Docker path instead of "Python 3.x".

Verified: mkdocs build on the host and inside the new image both exit 0 with zero TypeDoc errors and the same 134 API module pages; the setup script builds a 3.12 venv with a working mkdocs where Python 3.12 is available and fails with python3.12: command not found where it is not; actionlint, markdownlint and Biome pass.

Issue number: closes #5647

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.