Skip to content

claude: support anchor redirects in docs redirect extension - #4812

Open
Liam-DeVoe wants to merge 1 commit into
HypothesisWorks:masterfrom
Liam-DeVoe:docs-redirect-anchors
Open

claude: support anchor redirects in docs redirect extension#4812
Liam-DeVoe wants to merge 1 commit into
HypothesisWorks:masterfrom
Liam-DeVoe:docs-redirect-anchors

Conversation

@Liam-DeVoe

Copy link
Copy Markdown
Member
Claude-written description

Replaces the vendored sphinx-reredirects extension and its hand-maintained redirect.html.template with a purpose-built redirect extension supporting both page redirects and per-anchor redirects, declared together in the redirects dict in conf.py.

The main improvement is anchor handling on removed pages. When dead-page redirects to new-page#section, a visit to dead-page#some-anchor now resolves in order of preference: an explicit dead-page#some-anchor entry, then new-page#some-anchor if that id still exists on the target page, then new-page#section. Previously anchors were carried over unconditionally, landing on the target page with a broken fragment whenever the anchor no longer existed there.

Anchor redirects also work on live pages: an entry like live-page#moved-anchor injects a small script into that page which redirects only when the visited fragment no longer exists on it.

All redirect sources and targets are now validated at docs build time against the built doctrees — a target page or anchor that doesn't exist, a stub that would shadow a real page, or a live-page anchor entry whose anchor still exists all fail the build. This replaces the old linkcheck-based checking (which only covered external targets) and means the expanded redirect map in conf.py can't silently rot.

The old extension's wildcard sources, template file config, and linkcheck integration were unused here and are dropped.

No RELEASE.rst since this only touches docs/.

Comment thread hypothesis/docs/conf.py
Comment on lines +91 to +95
"details#hypothesis.assume": "reference/api#hypothesis.assume",
"details#hypothesis.event": "reference/api#hypothesis.event",
"details#hypothesis.given": "reference/api#hypothesis.given",
"details#hypothesis.infer": "reference/api#hypothesis.infer",
"details#hypothesis.note": "reference/api#hypothesis.note",

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can't these be handled by a page-level redirect, and then finding an anchor on the new page which matches that on the old page?

@Liam-DeVoe Liam-DeVoe Jul 22, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the problem for these specifically is we already have a "details": "reference/index.html" redirect, and want to override that redirect only for some specific anchors

details was a big catchall page that doesn't have a single canonical redirect

@Liam-DeVoe

Copy link
Copy Markdown
Member Author

sorry I told claude to open this PR and had intended to edit the description but got pulled away

I built this list by asking claude to find all extant and broken links to hypothesis on the internet. It (1) looked on stackoverflow, github search, etc, and (2) also somewhat misinterpreted and looked on the internet archive for old docs versions and pulled down the full anchor list at that time (regardless of whether anyone on the internet actually linked to it).

I kept ~all of the first category and only kept the mostly-reasonable ones in the second category.

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.

2 participants