Sphinx linkcheck fails for GitHub link with anchor in CI

[serixscorpio]

Problem

Sphinx linkcheck fails for https://github.com/pypa/pip/blob/main/setup.py#L11 in CI.

This is likely due to Github making the file viewer require Javascript, which breaks linkcheck's anchor checks.

Approaches

From specific to general:

1. Remove this link or remove the anchor portion of this link. This might degrade clarity of documentation and future use of github links with anchor would break CI.
2. Ignore linkcheck for this single link. However, if another github link with anchor is added to documentation, CI would break again.
3. Disable linkcheck for github links with anchor. A regex can be used to detect github links with anchor. See also feature request to Sphinx: Allow disabling linkcheck anchor checks for specific URLs sphinx-doc/sphinx#11484. But github links with anchor (current and in the future) can rot.
4. Ignore Github links altogether. However, there are many github links currently in use.

For now I'm leaning towards approach 2 or 3.

[webknjaz]

There were attempts in the past to fix this for GitHub but were reverted: sphinx-doc/sphinx#9016 (comment).

I think that prefixing the anchors with user-content- — these do exist in the actual HTML, unlike the generated ones: https://github.com/sphinx-doc/sphinx/pull/9260/files#diff-a00408d73754dd42b50d138c9927590014dcdd58f079c57c7cfe89a33fb9575aR663.

[di]

@webknjaz That doesn't seem to work: https://github.com/pypa/packaging.python.org/actions/runs/5728400351/job/15522879153?pr=1279

[webknjaz]

@di oh, it looks like they've changed the HTML layout to remove those anchors from the initial HTTP response entirely, and it's all being rendered on the front end now. I suppose we just need to mass-ignore any GH code-line anchors, after all...

[di]

I'm just going to drop the anchor here, it doesn't seem specifically necessary.

[webknjaz]

Made a suggestion here: https://github.com/pypa/packaging.python.org/pull/1279/files#r1280808096

[chrysle]

There is the config value linkcheck_anchors_ignore for Sphinx. I think we could employ this to allow adding GitHub anchors.