Summary
npm run docs:local:setup creates a venv with the system python3 and installs docs/requirements.txt. The pins in that file (click==8.5.0, mkdocs-material==9.7.7) require Python 3.10 or newer, and the docs workflow runs on 3.12, but nothing in the repo records the requirement. On a host whose python3 is 3.9 the install fails with "No matching distribution found for click==8.5.0", and CONTRIBUTING.md and docs/contributing/setup.md say only "if you have Python installed".
Why is this needed?
The local docs build is the only way to exercise the TypeDoc API Reference before a docs publish, since PR CI does not run it (see #5646). A setup script that fails on a common default interpreter, with no hint about why, discourages the one check that would catch API Reference regressions.
Which area does this relate to?
Automation, Governance
Solution
- Add a
.python-version file pinning 3.12, matching the docs workflow.
- Point the docs workflow's
actions/setup-python step at that file with python-version-file, so the pin is the single source of truth for CI too.
- Change
docs:local:setup to python3.12 -m venv .venv && .venv/bin/pip install --require-hashes -r docs/requirements.txt. A machine without 3.12 then fails immediately with "command not found" instead of an opaque resolution error, and local installs get the same hash check CI and the docs Dockerfile already apply.
- Update both contributor pages to name Python 3.12 as the prerequisite for the non-Docker path. Docker remains the zero-install alternative.
Acknowledgment
Future readers
Please react with 👍 and your use case to help us understand customer demand.
Summary
npm run docs:local:setupcreates a venv with the systempython3and installsdocs/requirements.txt. The pins in that file (click==8.5.0,mkdocs-material==9.7.7) require Python 3.10 or newer, and the docs workflow runs on 3.12, but nothing in the repo records the requirement. On a host whosepython3is 3.9 the install fails with "No matching distribution found for click==8.5.0", and CONTRIBUTING.md anddocs/contributing/setup.mdsay only "if you have Python installed".Why is this needed?
The local docs build is the only way to exercise the TypeDoc API Reference before a docs publish, since PR CI does not run it (see #5646). A setup script that fails on a common default interpreter, with no hint about why, discourages the one check that would catch API Reference regressions.
Which area does this relate to?
Automation, Governance
Solution
.python-versionfile pinning3.12, matching the docs workflow.actions/setup-pythonstep at that file withpython-version-file, so the pin is the single source of truth for CI too.docs:local:setuptopython3.12 -m venv .venv && .venv/bin/pip install --require-hashes -r docs/requirements.txt. A machine without 3.12 then fails immediately with "command not found" instead of an opaque resolution error, and local installs get the same hash check CI and the docs Dockerfile already apply.Acknowledgment
Future readers
Please react with 👍 and your use case to help us understand customer demand.