# Sphinx linkcheck and broken/redirect occurrences in Python Docs **URL:** \ **Category:** Documentation\ **Created:** [April 11, 2023, 11:09am UTC](https://discuss.python.org/t/sphinx-linkcheck-and-broken-redirect-occurrences-in-python-docs/25687 "2023-04-11T11:09:46Z")\ **Posts on this page:** 7\ **Page:** 1
**Author:** ![rffontenelle](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/rffontenelle/32/4568_2.png) [@rffontenelle](https://discuss.python.org/u/rffontenelle)\ **Post date:** [April 11, 2023, 11:09am UTC](https://discuss.python.org/t/sphinx-linkcheck-and-broken-redirect-occurrences-in-python-docs/25687/1 "2023-04-11T11:09:46Z")
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](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-linkcheck_ignore) and [linkcheck\_allowed\_redirects](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-linkcheck_allowed_redirects) were appropriate. ---
**Author:** ![hugovk](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/hugovk/32/14505_2.png) [@hugovk](https://discuss.python.org/u/hugovk)\ **Post date:** [April 11, 2023, 12:40pm UTC](https://discuss.python.org/t/sphinx-linkcheck-and-broken-redirect-occurrences-in-python-docs/25687/2 "2023-04-11T12:40:23Z")
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](https://github.com/hugovk/github-tools/blob/main/bpo_redirecter.py) 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. ---
**Author:** ![rffontenelle](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/rffontenelle/32/4568_2.png) [@rffontenelle](https://discuss.python.org/u/rffontenelle)\ **Post date:** [April 11, 2023, 1:07pm UTC](https://discuss.python.org/t/sphinx-linkcheck-and-broken-redirect-occurrences-in-python-docs/25687/3 "2023-04-11T13:07:10Z")
Hi Hugo. Thanks for your reply. Regarding BPO being redirected to GitHub, I figured out the following setting in `Doc/conf.py`: ```auto 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? ---
**Author:** ![hugovk](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/hugovk/32/14505_2.png) [@hugovk](https://discuss.python.org/u/hugovk)\ **Post date:** [April 11, 2023, 1:33pm UTC](https://discuss.python.org/t/sphinx-linkcheck-and-broken-redirect-occurrences-in-python-docs/25687/4 "2023-04-11T13:33:09Z")
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? ```python linkcheck_ignore = [ 'https://bugs.python.org/issue?@action=redirect&bpo=' ] ``` There’s also some [`linkcheck_allowed_redirects` and `linkcheck_ignore` rules in the devguide](https://github.com/python/devguide/blob/79e1a1f2961ba0882d5f0274f7c8876e36ca5dff/conf.py#L60-L107) 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](https://devguide.python.org) has general contributing advice, and feel free to ask more here or in the PR. Thanks! ---
**Author:** ![rffontenelle](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/rffontenelle/32/4568_2.png) [@rffontenelle](https://discuss.python.org/u/rffontenelle)\ **Post date:** [April 11, 2023, 1:52pm UTC](https://discuss.python.org/t/sphinx-linkcheck-and-broken-redirect-occurrences-in-python-docs/25687/5 "2023-04-11T13:52:02Z")
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)? ---
**Author:** ![hugovk](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/hugovk/32/14505_2.png) [@hugovk](https://discuss.python.org/u/hugovk)\ **Post date:** [April 11, 2023, 1:55pm UTC](https://discuss.python.org/t/sphinx-linkcheck-and-broken-redirect-occurrences-in-python-docs/25687/6 "2023-04-11T13:55:01Z")
Sure, we can use an issue, especially if it makes things easier 👍 ---
**Author:** ![rffontenelle](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/rffontenelle/32/4568_2.png) [@rffontenelle](https://discuss.python.org/u/rffontenelle)\ **Post date:** [April 12, 2023, 7:28pm UTC](https://discuss.python.org/t/sphinx-linkcheck-and-broken-redirect-occurrences-in-python-docs/25687/7 "2023-04-12T19:28:42Z")
Issue open, some questions listed in there. > > > Running \`make linkcheck\` in Doc folder outputs thousands of broken and redirecte…d status. It would be nice to clean this up so we can link-check Python in CI/CD for each commit, but right now it is too polluted. > > Some of these occurrences could/should be fixed in the docs itself, others can benefit from \[Sphinx's linkcheck configs\](https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder) e.g. \`linkcheck\_ignore\` and \`linkcheck\_allow\_redirect\`. > > See \[linkcheck-log.txt\](https://github.com/python/cpython/files/11215133/linkcheck-log.txt) for the full log as of commit f2b7ecb. > > Fun stats obtained from the above file: > \- Of its 8327 lines, where 7824 are related to BPO -\> GH issues. Of 7824, 5744 lines are from whatsnew/changelog and only 20 are not from whatsnew/ > \- 241 lines are redirection of CPython CVS URL, fixing /tree/ to /blob/ in GitHub URL > \- 28 lines are broken links, where one broken link is 'https://' from an example in whatsnet/changelog > > The way I see, this steps divide in: > \- Clean BPO to GH redirection messages > \- Fix broken links > \- Clean CPython CVS URL redirections > \- Clean GH issues to GH PR redirections > \- Fix the rest of the occurrences. > > linkcheck\_allow\_redirect and linkcheck\_ignore can be very handy in this case. linkcheck\_allow\_redirect makes 'ok' status a redirect that is being spotted by linkcheck, and we have linkcheck\_ignore as the last resource. > > Questions I have before implementing the solution: > \* Documentation hosted by Read The Docs may have language enabled so example.com is redirected to example.com/en/latest. To handle occurrences, I could add them to linkcheck\_allow\_redirect or we can use \[sphinx-ext-intersphinx\](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) to map a keyword to the documentation URL (e.g 'rtd' for read-the-docs docs). The last option allows to map to proper language of the target URL linked, similar on how \[Weblate did\](https://github.com/WeblateOrg/weblate/blob/main/docs/conf.py#L213)) > \- Is there any restrictions to fix broken/redirect links in old whatsnew/\.rst? > \- Is there any restrictions to fix broken/redirect links in old whatsnew/changelog.rst (i.e. Misc/NEWS)? > \- Should I create a single Pull Request for all the fixes?