docs: repoint nine dead source links in the onboarding guide - #4025
Merged
gaborbernat merged 2 commits intoAug 13, 2026
Merged
Conversation
Nine ``blob/main`` links in docs/onboarding.rst referenced paths that do
not exist in main, so they rendered as GitHub 404s. Six of them also
labelled the link with a class or module name that no longer exists.
Resolved each against the tree and the class definitions rather than
guessing:
- session/cmd/list_envs.py -> session/cmd/list_env.py
- session/cmd/show_config.py -> session/cmd/show_config/ (now a package)
- config/cli/env.py -> session/env_select.py (defines CliEnv)
- local_sub_process/execute_instance.py, execute_status.py
-> local_sub_process/__init__.py
- config/source/toml_.py -> config/source/toml_tox.py (TomlTox)
- config/source/pyproject.py -> config/source/toml_pyproject.py
(TomlPyProject)
- config/loader/ini.py -> config/loader/ini/__init__.py
- config/loader/toml.py -> config/loader/toml/__init__.py
All 67 blob links in docs/ now resolve to a file that exists. No new
lines exceed 120 characters.
Closes tox-dev#4024
for more information, see https://pre-commit.ci
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #4024.
tox -e fix)— not run: I could not install a working
toxin this environment. Instead I checkedthe rules
tox -e fixwould enforce on an RST-only diff by hand: no line introduced bythis change exceeds 120 characters (verified by script — the only lines over 120 in the
file are the four that were already over on
main), and the RST parses underdocutils.Please re-run
tox -e fixon my branch; I'll amend if it objects.— not applicable: the change contains no code. The equivalent check is the link
resolution described above (67 links in
docs/, 0 unresolved), which I ran before andafter. If you would find a repo-level guard against this class of regression useful, I'd
be glad to contribute one as a separate PR rather than smuggle it in here.
docs/changelogfolder —docs/changelog/4024.doc.rstProblem
Nine
blob/mainsource links indocs/onboarding.rstpoint at paths that do not exist inmain, so they render as GitHub 404s. Six of them additionally label the link with a class ormodule name that no longer exists, so the prose is misleading independently of the dead link.
This matters more than it would in most files because
onboarding.rstis what a newcontributor reads to learn where things live — these are exactly the links someone with no
prior knowledge of the layout will click.
How it was reproduced
I resolved every
https://github.com/tox-dev/tox/blob/main/<path>link indocs/against theworking tree at
main, rather than checking them over HTTP (GitHub rate-limits that hard enoughto produce false positives in both directions):
All nine were in
onboarding.rst; the other 58 were already correct and are untouched.What the fix does
Each link was resolved by locating the definition it refers to, not by guessing at a
similar-looking filename:
session/cmd/list_envs.pysession/cmd/list_env.py(singular; it registers thelistcommand)session/cmd/show_config.pysession/cmd/show_config/— became a package in #3857config/cli/env.pysession/env_select.py, whereCliEnvis definedlocal_sub_process/execute_instance.pylocal_sub_process/__init__.py, label →LocalSubProcessExecuteInstance.start()local_sub_process/execute_status.pylocal_sub_process/__init__.py, label →LocalSubprocessExecuteStatus.wait()config/source/toml_.py, labelledTomlSourceconfig/source/toml_tox.py, labelledTomlToxconfig/source/pyproject.py, labelledPyProjectTomlSourceconfig/source/toml_pyproject.py, labelledTomlPyProjectconfig/loader/ini.pyconfig/loader/ini/__init__.pyconfig/loader/toml.pyconfig/loader/toml/__init__.pyThe
tox.toml→TomlToxandpyproject.toml→TomlPyProjectsplit was confirmed againstthe import order in
src/tox/config/source/discover.pyso the two are not transposed.Documentation only — no source changes, and no links outside the nine broken ones were touched.
How it was verified
docs/, 0 broken.referencenode viadocutils(80 reference nodes in the file), so none of them silently became plain text — relevant
because two of the fixed links wrap across lines.
docs/development.rst. Two of my edits initially pushedtheir lines to 122 and 123, so I reflowed them: the
show_configcell now wraps using thesame 8-space continuation style already used by the
sequential.pycell in that samelist-table. Lines over 120 in the file are now exactly the four that were already over onmain(5, 72, 410, 680) — the change adds none.(
LocalSubProcessExecuteInstanceatlocal_sub_process/__init__.py:162,LocalSubprocessExecuteStatusat:62,IniLoaderatloader/ini/__init__.py:35,TomlLoaderatloader/toml/__init__.py:31,CliEnvatsession/env_select.py:41).I could not run
tox -e docsin this environment, so the RST was validated withdocutilsrather than a full Sphinx build. The change is confined to link targets and link labels inside
existing constructs, so I would not expect a Sphinx-specific failure, but please flag it if the
docs build disagrees.
Changelog entry added as
docs/changelog/4024.doc.rst. If you would rather keep the abstractExecuteInstance/ExecuteStatusnames in the prose at lines 447/450 and only repoint theURLs, say so and I'll amend.
Disclosure: this change was prepared with AI assistance. The link resolution, the
docutilsreference-node check and the line-length comparison described above were actually run, and I
have reviewed every one of the nine mappings against the class definitions in the tree.
Flagging it so reviewers can weigh it as they see fit.