Re: [Django] #32723: Add a GitHub action to run the Sphinx linkcheck builder.
Django
-------------------------------------+-------------------------------------
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 Sarah Abderemane):
Nick Pope any news on this subject ?
--
Ticket URL: <https://code.djangoproject.com/ticket/32723#comment:5>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
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 Jacob Walls):
Hey Sarah. Took a look myself. I believe Nick was hoping for changes in
Sphinx to allow regexes like these [https://github.com/sphinx-
doc/sphinx/issues/6525#issuecomment-828730361 like these] with
backreferences, but testing against the latest version of Sphinx, they
aren't supported:
{{{
WARNING: Failed to compile regex in linkcheck_allowed_redirects:
'^https://\\1\\.readthedocs\\.io/[-a-z]+/(?:master|latest|stable)/$'
invalid group reference 1
WARNING: Failed to compile regex in linkcheck_allowed_redirects:
'^https://docs\\.djangoproject\\.com/\\1/\\d+\\.\\d+/' invalid group
reference 1
}}}
However the released Sphinx changes ''would'' allow regexes without the
backreferences. So if we were to get started now with implementing this in
Django, we would, say, in the case of the readthedocs.io links, either
need to use looser regexes (possibly allowing one readthedocs site to
redirect to another readthedocs site, etc) or need to write regexes for
each readthedocs site (ouch?)
I don't have a strong opinion, but I would say the former option (just
remove the backreferences and allow looser matches) seems tolerable. We're
perfectionists who don't mind using imperfect tools, right? :wink: We
could then tighten up the regexes once someone submits a follow-up PR to
Sphinx. A second opinion would be good to get before setting to work,
though.
I think the triage stage is set to Maybe because there might be objections
to running this on CI vs. manually, but that doesn't bear directly on
whether we should get the regexes written to use the new Sphinx feature.
--
Ticket URL: <https://code.djangoproject.com/ticket/32723#comment:6>
Django
-------------------------------------+-------------------------------------
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 Nick Pope):
Thanks for looking into this Jacob.
So, yes, I was waiting for the feature to be added to Sphinx, but there
were some complications over the implementation, so it is only part of
what would be needed. It's on my very long list of things to look into.
The main problem is that substituting the captures from the source pattern
into the target pattern using back-references precludes the use of back-
references for repeating captured groups within the target pattern.
At this stage I think we still need to wait until something further is
implemented in Sphinx. That is why I flagged this "Someday/Maybe". I think
we'd require a great many more entries because we can't make it generic
enough. On top of that, one of the reasons for wanting to be able to
substitute from the source to the target is to ensure that we're actually
redirected to the right page. This whole thing is intended to make
linkcheck useful for documentation sites that redirect for language and
version, but not mask other potential issues.
--
Ticket URL: <https://code.djangoproject.com/ticket/32723#comment:7>
Django
-------------------------------------+-------------------------------------
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 Sarah Abderemane):
Thanks Nick and Jacob for your replies. I understand better what it
implies to do before this ticket, I'll follow up to see how it will
involves.
I agree, the triage stage is confusing, even more for me when I didn't
know what it implies really. I think it will be good to have many more
entries for better understanding for everyone.
--
Ticket URL: <https://code.djangoproject.com/ticket/32723#comment:8>
Django
-------------------------------------+-------------------------------------
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 Ralph Reid):
Hi Sarah, I have some spare cycles to help out. Has the closed reference
ticket https://github.com/sphinx-doc/sphinx/issues/6525 moved this ticket
further?
Thanks.
--
Ticket URL: <https://code.djangoproject.com/ticket/32723#comment:9>
Django
-------------------------------------+-------------------------------------
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 Sarah Abderemane):
Hi Ralph, I was waiting this issue to be resolved https://github.com
/sphinx-doc/sphinx/issues/9234 and the triage stage to be changed.
Nick or Jacob, or someone else who have the knowledge, do you think it's
ok to change the triage stage or there are some stuff to be checked before
to change the status of this ticket ?
--
Ticket URL: <https://code.djangoproject.com/ticket/32723#comment:10>
Django
-------------------------------------+-------------------------------------
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 Nick Pope):
My previous comment above still stands - it was posted after that change
to Sphinx was merged.
The change made was only part of the solution, so we cannot really
progress here yet.
--
Ticket URL: <https://code.djangoproject.com/ticket/32723#comment:11>
Django
-------------------------------------+-------------------------------------
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 Sarah Abderemane):
Sorry for the inconvenience Nick, thanks for the quick response. I will
check if the triage status only changes.
--
Ticket URL: <https://code.djangoproject.com/ticket/32723#comment:12>