Skip to content

docs: repoint nine dead source links in the onboarding guide - #4025

Merged
gaborbernat merged 2 commits into
tox-dev:mainfrom
Yusuf-Gadelrab:docs/fix-onboarding-source-links
Aug 13, 2026
Merged

docs: repoint nine dead source links in the onboarding guide#4025
gaborbernat merged 2 commits into
tox-dev:mainfrom
Yusuf-Gadelrab:docs/fix-onboarding-source-links

Conversation

@Yusuf-Gadelrab

@Yusuf-Gadelrab Yusuf-Gadelrab commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

Closes #4024.

  • ran the linter to address style issues (tox -e fix)
    not run: I could not install a working tox in this environment. Instead I checked
    the rules tox -e fix would enforce on an RST-only diff by hand: no line introduced by
    this 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 under docutils.
    Please re-run tox -e fix on my branch; I'll amend if it objects.
  • wrote descriptive pull request text
  • ensured there are test(s) validating the fix
    — 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 and
    after. 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.
  • added news fragment in docs/changelog folder — docs/changelog/4024.doc.rst
  • updated/extended the documentation — this PR is the documentation change

Problem

Nine blob/main source links in docs/onboarding.rst point at paths that do not exist in
main, so they render as GitHub 404s. Six of them additionally label the link with a class or
module 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.rst is what a new
contributor 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 in docs/ against the
working tree at main, rather than checking them over HTTP (GitHub rate-limits that hard enough
to produce false positives in both directions):

links resolving to an existing file: 58
links pointing at a NON-EXISTENT path: 9

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:

Line Was Now
304 session/cmd/list_envs.py session/cmd/list_env.py (singular; it registers the list command)
308 session/cmd/show_config.py session/cmd/show_config/ — became a package in #3857
370 config/cli/env.py session/env_select.py, where CliEnv is defined
447 local_sub_process/execute_instance.py local_sub_process/__init__.py, label → LocalSubProcessExecuteInstance.start()
450 local_sub_process/execute_status.py local_sub_process/__init__.py, label → LocalSubprocessExecuteStatus.wait()
549 config/source/toml_.py, labelled TomlSource config/source/toml_tox.py, labelled TomlTox
551 config/source/pyproject.py, labelled PyProjectTomlSource config/source/toml_pyproject.py, labelled TomlPyProject
589 config/loader/ini.py config/loader/ini/__init__.py
591 config/loader/toml.py config/loader/toml/__init__.py

The tox.tomlTomlTox and pyproject.tomlTomlPyProject split was confirmed against
the import order in src/tox/config/source/discover.py so the two are not transposed.

Documentation only — no source changes, and no links outside the nine broken ones were touched.

How it was verified

  • Re-ran the same tree resolution after the change: 67 blob links in docs/, 0 broken.
  • Confirmed each of the nine new targets parses into a real reference node via docutils
    (80 reference nodes in the file), so none of them silently became plain text — relevant
    because two of the fixed links wrap across lines.
  • Checked the 120-character rule from docs/development.rst. Two of my edits initially pushed
    their lines to 122 and 123, so I reflowed them: the show_config cell now wraps using the
    same 8-space continuation style already used by the sequential.py cell in that same
    list-table. Lines over 120 in the file are now exactly the four that were already over on
    main (5, 72, 410, 680) — the change adds none.
  • Verified the class and module names by grepping for their definitions
    (LocalSubProcessExecuteInstance at local_sub_process/__init__.py:162,
    LocalSubprocessExecuteStatus at :62, IniLoader at loader/ini/__init__.py:35,
    TomlLoader at loader/toml/__init__.py:31, CliEnv at session/env_select.py:41).

I could not run tox -e docs in this environment, so the RST was validated with docutils
rather 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 abstract
ExecuteInstance / ExecuteStatus names in the prose at lines 447/450 and only repoint the
URLs, say so and I'll amend.

Disclosure: this change was prepared with AI assistance. The link resolution, the docutils
reference-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.

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
@gaborbernat
gaborbernat merged commit 4636193 into tox-dev:main Aug 13, 2026
55 of 57 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: nine source links in onboarding.rst point at paths that no longer exist

2 participants