docs: troubleshoot stale .nodeenv blocking local tox/install#405
Conversation
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 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #405 +/- ##
=======================================
Coverage ? 47.75%
=======================================
Files ? 2
Lines ? 423
Branches ? 0
=======================================
Hits ? 202
Misses ? 221
Partials ? 0
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
Adds developer documentation for a common local setup failure mode where a stale, git-ignored .nodeenv/ (created by sphinx-theme-builder) blocks tox / editable installs due to a Node version mismatch, and clarifies which build/test artifacts stay repo-local.
Changes:
- Documented that
tox,.tox/,.nodeenv/, andnode_modules/are repo-local and safe to delete/recreate. - Added a troubleshooting section for
nodeenv-version-mismatch, including the one-line remediation (rm -rf .nodeenv). - Recorded the documentation update in
CHANGELOG.md.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/developer/setup.md | Adds “repo-local” clarification and a troubleshooting guide for stale .nodeenv/ blocking tox / editable installs. |
| CHANGELOG.md | Notes the new developer setup troubleshooting documentation under Unreleased. |
| 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. |
| and the expected version of NodeJS (v20.18.0). | ||
| ``` | ||
|
|
||
| your in-repo `.nodeenv/` is stale — it was provisioned against an older pinned |
🎭 Visual Regression Test Results
Details
Skipped testsdesktop-chrome › theme.spec.ts › Visual Regression Tests › prob-matrix - full page screenshot |
Summary
Documents a local dev-environment gotcha that currently blocks
toxand editable installs: a stale in-repo.nodeenv/(left over from an older pinned Node.js version) aborts the build with anodeenv-version-mismatcherror before any tests run. This surfaced while setting up a clean local environment to test #404.No code or toolchain change — docs only. The fix is simply to delete the git-ignored
.nodeenv/and letsphinx-theme-builderrebuild it.What this adds to
docs/developer/setup.mdnodeenv-version-mismatcherror and its one-line fix (rm -rf .nodeenvthen rebuild), with a pointer to thenode-versionpin under[tool.sphinx-theme-builder]inpyproject.toml.toxisolates the toolchain to the repository —.tox/,.nodeenv/, andnode_modules/are all git-ignored and regenerated, so the test/build environment never touches the base/global Python or Node.Verification
After
rm -rf .nodeenv, the isolatedtox -e py313-sphinx7run provisions a fresh.nodeenv, compiles assets, installs the[test]extras, and passes the full suite (106 tests) — confirming the documented remedy.Note on Node versions
For context (not changed here):
sphinx-theme-builderpins its internal Node to20.18.0inpyproject.toml, while.nvmrc, the dev docs, and CI's visual jobs use Node 24. These serve different paths (stb's packaging build vs. thenpm/Playwright build) and both work today, so I've left the pin alone. If we'd prefer stb to also build on Node 24 for consistency, that can be a separate follow-up.🤖 Generated with Claude Code