docs(tooling): add a troubleshooting entry for "autoformat on save" with ruff not working

[danceratopz]

Problem symptoms

1. Open a Python module in VS Code (not all files will be effected; src/ethereum_test_specs/blockchain.py@8fbca341fb triggered this issue).
2. Add a newline and save in order to trigger an "autoformat upon save".
3. If correctly configured, the newline should have be deleted and the file should not have any differences (git diff). If the problem is present, the file will have differences and, in particular, tox -e lint fails.

One possible cause

Incorrect Python virtual environment configured for the execution-spec-tests VS Code Workspace.

If the configured venv doesn't have ruff installed, then the ruff extension (charliermarsh.ruff) falls back to using the ruff executable that is bundled with VS Code. This bundled version (0.9.1) currently doesn't match the pinned in execution-spec-tests' pyproject.toml (0.8.2) which leads to different behavior between autosave and tox -e lint.

It could also fail if the venv has a different version of ruff installed.

Debugging

Check the output of the "Ruff Language Server" Output tab, which will warn that it's using the bundled version:

Interpreter executable (/home/dtopz/code/github/danceratopz/eest/.venv/bin/ruff) not found
Falling back to bundled executable: /home/dtopz/.vscode/extensions/charliermarsh.ruff-2025.2.0-linux-x64/bundled/libs/bin/ruff
Found ruff 0.9.1 at /home/dtopz/.vscode/extensions/charliermarsh.ruff-2025.2.0-linux-x64/bundled/libs/bin/ruff
Ignoring unsupported argument: --fix
Running Ruff with: /home/dtopz/.vscode/extensions/charliermarsh.ruff-2025.2.0-linux-x64/bundled/libs/bin/ruff ['check', '--force-exclude', '--no-cache', '--no-fix', '--quiet', '--output-format', 'json', '-', '--line-length', '99', '--stdin-filename', '/home/dtopz/code/github/danceratopz/eest/src/ethereum_test_specs/blockchain.py']

Solution

1. In VS Code use <ctrl>+<shift>+p -> Type "Python: Select Interpreter"
2. Select the .venv folder (that is created by uv and used by tox).

[danceratopz]

This can also simply happen if, .venv is not present and the developer forgets to run uv sync --all-extras.

Upon running fill, eest's direct package dependencies get installed by uv, but not the lint extras. All seems well, but VS Code will not be correctly configured and lead to the same issue.