From 4703243691cdfebd7711181fc6e27b0c91a58ddb Mon Sep 17 00:00:00 2001 From: Matt McKay Date: Fri, 19 Jun 2026 13:32:17 +1000 Subject: [PATCH 1/2] docs: troubleshoot stale .nodeenv blocking local tox/install MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the `nodeenv-version-mismatch` error that occurs when the in-repo `.nodeenv/` is left over from an older pinned Node.js version — it aborts `tox` and `pip install -e .` before tests can run. The fix is to delete `.nodeenv/` and let sphinx-theme-builder rebuild it. Also clarify that `tox` keeps the toolchain fully repo-local (`.tox/`, `.nodeenv/`, `node_modules/` are all git-ignored and regenerated), so the test/build environment never touches the base/global Python or Node. Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 3 +++ docs/developer/setup.md | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 38 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index cbf38cf..5157d66 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Documentation +- **Developer setup troubleshooting for stale `.nodeenv`** — documented the `nodeenv-version-mismatch` error (an in-repo `.nodeenv/` left over from an older pinned Node.js version) and its fix (`rm -rf .nodeenv` then rebuild), which otherwise blocks `tox` and editable installs locally. Also clarified that `tox` keeps the toolchain fully repo-local (`.tox/`, `.nodeenv/`, `node_modules/` are all git-ignored and regenerated), so nothing is installed into the base/global environment. + ### CI - **CI Node bumped 20 → 24** — Node 20 reached end-of-life in April 2026, and the grouped npm updates in #400 raised engine floors (`sass-loader` 17 requires Node ≥22.11). Node 24 is the current active LTS (supported to April 2028). Applies to `ci.yml`, `docs.yml`, and `update-snapshots.yml`; `.nvmrc` and the contributor docs (`CONTRIBUTING.md`, `docs/developer/setup.md`) move to Node 24 in step so local dev matches CI. - **Stabilized flaky mobile-chrome visual tests on math-heavy pages** — after the Playwright 1.57→1.60 (Chromium) bump in #400, `math`/`proofs`/`cross-references` full-page screenshots intermittently rendered ~60px shorter than baseline, failing Playwright's dimension check before pixel tolerances apply. `waitForReady` now waits for `document.fonts.ready` and polls until the document height holds steady for 750ms, instead of a fixed 500ms sleep after MathJax typesetting. diff --git a/docs/developer/setup.md b/docs/developer/setup.md index 80fc97b..d8b85e0 100644 --- a/docs/developer/setup.md +++ b/docs/developer/setup.md @@ -77,6 +77,16 @@ See [Testing](testing.md) for detailed information about test fixtures and writing new tests. ::: +### Everything stays repo-local + +`tox` keeps the toolchain isolated to this repository — it builds its +virtualenvs under `.tox/` and installs the package plus its `[test]` extras +there, never into your base/global Python. The theme's SCSS/JS assets are +compiled by `sphinx-theme-builder`, which provisions its own Node.js into an +in-repo `.nodeenv/` (with `node_modules/` for `npm`). All three directories are +git-ignored, so nothing leaks system-wide and the environment can always be +rebuilt from scratch by deleting them. + ## Code Style ### Python @@ -96,3 +106,28 @@ writing new tests. - Modern `@use` / `@forward` syntax (not `@import`) - BEM-inspired class naming - Maximum 3–4 levels of nesting + +## Troubleshooting + +### `nodeenv-version-mismatch` when running `tox` or installing + +If `tox` (or a `pip install -e .`) fails with something like: + +```text +× The `nodeenv` for this project is unhealthy. +╰─> There is a mismatch between what is present in the environment (v18.18.0) + and the expected version of NodeJS (v20.18.0). +``` + +your in-repo `.nodeenv/` is stale — it was provisioned against an older pinned +Node.js version and never refreshed. `sphinx-theme-builder` rebuilds it +automatically once it's removed: + +```console +$ rm -rf .nodeenv +$ tox +``` + +The pinned version lives under `[tool.sphinx-theme-builder]` (`node-version`) +in `pyproject.toml`; deleting `.nodeenv/` is always safe since it is git-ignored +and regenerated on the next build. From b7fe608c306a28bae57a84f164db03a6ba5e982e Mon Sep 17 00:00:00 2001 From: Matt McKay Date: Thu, 6 Aug 2026 13:31:16 +1000 Subject: [PATCH 2/2] docs: clarify repo-local dirs and tighten troubleshooting intro Address Copilot review on #405. The "(with node_modules/ for npm)" parenthetical hung off .nodeenv/ and could be read as node_modules/ living inside it. Split it into its own clause and name all three directories explicitly where "all three" is claimed. The troubleshooting intro ran a single sentence across the error code block, which left it resuming on a lowercase "your". Reword the intro to close before the block so the following sentence starts cleanly. Co-Authored-By: Claude Opus 5 (1M context) --- docs/developer/setup.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/developer/setup.md b/docs/developer/setup.md index d8b85e0..fbc8ebe 100644 --- a/docs/developer/setup.md +++ b/docs/developer/setup.md @@ -83,7 +83,8 @@ writing new tests. virtualenvs under `.tox/` and installs the package plus its `[test]` extras there, never into your base/global Python. The theme's SCSS/JS assets are compiled by `sphinx-theme-builder`, which provisions its own Node.js into an -in-repo `.nodeenv/` (with `node_modules/` for `npm`). All three directories are +in-repo `.nodeenv/`; `npm` then installs into `node_modules/` at the repository +root. All three directories — `.tox/`, `.nodeenv/`, and `node_modules/` — are git-ignored, so nothing leaks system-wide and the environment can always be rebuilt from scratch by deleting them. @@ -111,7 +112,7 @@ rebuilt from scratch by deleting them. ### `nodeenv-version-mismatch` when running `tox` or installing -If `tox` (or a `pip install -e .`) fails with something like: +`tox` (or a `pip install -e .`) may fail with something like this: ```text × The `nodeenv` for this project is unhealthy. @@ -119,7 +120,7 @@ If `tox` (or a `pip install -e .`) fails with something like: and the expected version of NodeJS (v20.18.0). ``` -your in-repo `.nodeenv/` is stale — it was provisioned against an older pinned +Your in-repo `.nodeenv/` is stale — it was provisioned against an older pinned Node.js version and never refreshed. `sphinx-theme-builder` rebuilds it automatically once it's removed: