Skip to content

📝 docs: fix trailing-slash links left by the Sphinx move - #1986

Merged
gaborbernat merged 1 commit into
pypa:mainfrom
marko1olo:fix/docs-trailing-slash-urls
Jul 29, 2026
Merged

gaborbernat merged 1 commit into
pypa:mainfrom
marko1olo:fix/docs-trailing-slash-urls

Conversation

@marko1olo

Copy link
Copy Markdown
Contributor

Closes #1980.

The Release Notes link in pyproject.toml is the one @kevinbowen777 reported, and it turned out not to be alone — the same MkDocs directory-URL shape survives in six more places. MkDocs served every page as a directory, so a link to one ended in a slash; #1957 moved the site to Sphinx, which emits <page>.html, and Read the Docs serves the built tree as is.

All seven, found by scanning rather than by eye:

pyproject.toml                    /latest/changelog/
.github/CONTRIBUTING.md           /latest/contributing/
.github/PULL_REQUEST_TEMPLATE.md  /latest/contributing/
docs/README.md                    /stable/explanation/comparisons/
docs/README.md                    /stable/how-to/install-pipx/          (x2)
docs/README.md                    /stable/contributing/

pyproject.toml and docs/README.md both feed the PyPI project page — the sidebar link and the long description respectively — so five of the seven are visible to anyone who lands there.

Checked against the live site rather than assumed: /latest/changelog.html and /stable/how-to/install-pipx.html answer 200, /latest/changelog/ answers 404.

The test

tests/test_docs_urls.py scans tracked documentation and pyproject.toml for the old shape so it cannot come back. Two notes on how it is built, since both were mistakes I made first:

  • It reads the tree with pathlib instead of shelling out to git ls-files. A subprocess call needs git on PATH, which is not guaranteed for whoever runs the suite.
  • Its terminator set includes quotes. My first version only matched a bare URL or a markdown link, so it silently passed over the one link the issue is actually about — the URL in pyproject.toml is inside a TOML string and ends at a ".

It needs neither network nor the package cache, so it runs anywhere the suite runs.

  • I have added a news fragment under changelog.d/
  • I have added a test

MkDocs served every page as a directory, so a link to one ended in a slash.
pypa#1957 moved the site to Sphinx, which emits <page>.html, and Read the Docs
serves the built tree as is, so the old shape 404s.

Seven links in tracked files still use it. The one reported in pypa#1980 is the
`Release Notes` entry in `pyproject.toml`, which is what PyPI renders in the
project sidebar; the rest are four links in `docs/README.md`, which is the
long description shown on the same page, and the contributor-guide link in
`.github/CONTRIBUTING.md` and the pull request template.

Checked against the live site rather than assumed:
`/latest/changelog.html` and `/stable/how-to/install-pipx.html` answer 200,
`/latest/changelog/` answers 404.

`tests/test_docs_urls.py` scans tracked documentation and `pyproject.toml`
for the MkDocs page shape so the pattern cannot come back. It reads the tree
with pathlib rather than shelling out, so it needs neither git on PATH nor
the package cache, and its terminator set covers a bare URL, a markdown link
and a quoted value — the last one because the reported link lives in a TOML
string.
@gaborbernat
gaborbernat merged commit fc7c6cc into pypa:main Jul 29, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Link to Release Notes on pypi.org/project/pipx is broken/incorrect

2 participants