#32723: Add a GitHub action to run the Sphinx linkcheck builder.
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Sarah
Type: | Abderemane
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: linkcheck, github, | Triage Stage:
action | Someday/Maybe
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Revant Khanna):
Another possible approach could be handling this at the workflow/tooling
level instead of adding dynamic backreference substitution support
directly inside Sphinx.
For example:
1. Run sphinx-build -b linkcheck
2. Generate output.json
3. Post-process the results using a small Python script
4. Filter or normalize acceptable redirect patterns before failing CI
This could provide a simpler and more maintainable solution for projects
with many predictable redirects.
Example idea:
ALLOWED = [
(
r"https://(.*)\.readthedocs\.io/en/latest/",
r"https://\1.readthedocs.io/en/stable/";
)
]
The post-processing script could:
-> compare original URLs against actual redirect targets
-> dynamically reconstruct expected redirect destinations using `re.sub`
-> suppress known/acceptable redirects
-> still fail for genuine broken links (404, DNS failures, SSL issues,
unexpected redirects, etc.)
After some additional testing, it appears that linkcheck already exposes
sufficient redirect metadata externally in output.json.
Example output:
{
"status": "redirected",
"uri": "http://github.com";,
"info": "https://github.com/";
}
Since both the original URL (uri) and redirect target (info) are
available, external tooling can already reconstruct and validate redirect
behavior dynamically without necessarily requiring substitution support
directly inside Sphinx core.
Potential advantages of this approach:
-> avoids increasing complexity inside Sphinx core
-> keeps `linkcheck` behavior simpler and more predictable
-> allows projects to implement project-specific redirect policies
externally
-> easier to iterate independently in CI workflows
-> provides more flexibility for custom CI filtering and redirect
validation logic
This may be especially useful for large projects like Django where many
redirects follow consistent patterns.
--
Ticket URL: <https://code.djangoproject.com/ticket/32723#comment:15>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/django-updates/0107019e65168bf9-12932acf-f3f3-4a4d-a6e4-1e525adaa343-000000%40eu-central-1.amazonses.com.
