Sphinx linkcheck and broken/redirect occurrences in Python Docs

Documentation
1

Using Sphinx’s linkcheck in Python Docs (cd Doc && make linkcheck SPHINXOPTS="--keep-going") I found thousand of lines of ‘redirect’ or ‘broken’ occurrences.

Is there any ongoing progress or previous discussion on this matter?

If not, I’d be willing to go through the docs fixing broken links, eliminating unnecessary redirects adding linkcheck_ignore and linkcheck_allowed_redirects were appropriate.

1 Like
2

Fixing the broken links would definitely be helpful.

Fixing redirects is not as important, but I think it’s fine to clean some of those up too.

Nearly all the redirects are links from the old tracker at https://bugs.python.org to the new one at https://github.com/python/cpython/issues. There’s a lot of them! I have a script that can automatically update BPO links to GitHub ones. Shall we update them? A big benefit: it would make the linkcheck output much cleaner and make it easier to run and fix linkcheck.

3

Hi Hugo. Thanks for your reply.

Regarding BPO being redirected to GitHub, I figured out the following setting in Doc/conf.py:

linkcheck_allowed_redirects = {
    r'https://bugs.python.org/issue\?@action=redirect&bpo=\d+': 'https://github.com/python/cpython/issues/\d+',
    ...
}

This turns ‘redirect’ status in ‘ok’ for linkcheck. It also makes whatsnew/changelog very happy.

But feel free to replace them.

Should I open an issue or maybe a PR as a tracker for discussing/providing fixes to this linkcheck topic?

4

Ah yes, linkcheck_allowed_redirects is a good idea, it’ll avoid lots of churn. Or because there’s so many (thousands?), is it any quicker to add it to linkcheck_ignore instead?

linkcheck_ignore = [
    'https://bugs.python.org/issue?@action=redirect&bpo='
]

There’s also some linkcheck_allowed_redirects and linkcheck_ignore rules in the devguide that could be useful in CPython docs too.

You can make a PR directly for this, we can skip issues for docs things, and you can ping me on the PR. If it touches lots of files, let’s split into smaller PRs. https://devguide.python.org has general contributing advice, and feel free to ask more here or in the PR.

Thanks!

5

Linkcheck shows more stuff to be fixed besides BPO->GH, like http → https, site redirect to new domain, docs in readthedocs being redirected to include /en/latest/ etc. To handle linkcheck’s broken/redirect status, all these would have to be dealt with.

Wouldn’t it make sense to have an issue to track these issues, and then PR for each (or maybe one PR with multiple commits)?

1 Like
6

Sure, we can use an issue, especially if it makes things easier :+1:

1 Like
7

Issue open, some questions listed in there.

3 Likes