Publish linkcheck failures at end of test

[Daltz333]

With a project with thousands of links, it can be a hassle searching through console or CI for the broken links and line numbers. It'd be great and convenient if Sphinx published the line numbers and broken link at the end of the linkcheck.

[tk0miya]

What do you mean "publish"?

[Daltz333]

Just text at the bottom of the build log

[mgeier]

@Daltz333 Note that the linkcheck builder creates an output.txt file which doesn't contain the successful checks (IIRC).

It does, however, include the re-directions, so it might still be hard to spot the broken links.

Also, there is a output.json file which you can process with a script if you want.

[tk0miya]

I think "line numbers" have already been displayed. I guess you'd like to know the name of document additionally, right?

$ make linkcheck
...
writing output... [100%] sub

(line    4) ok        https://www.google.co.jp/
(line    2) broken    https://www.example.com/path/ - 404 Client Error: Not Found for url: https://www.example.com/path/
build finished with problems, 1 warning.

[tk0miya]

Or, do you want to show the list of broken URLs instead of the whole of results?

[Daltz333]

Yep, the list of broken URLs instead of the whole result would work.

My original issue was hoping that immediately above "build finished with problems, 1 warning" would show the broken url right near it, so I don't have to scroll thousands of lines.

[tk0miya]

Okay, I understand your request. +1; Reasonable.

[AA-Turner]

cc: @jayaddison

I ran into this myself recently, I think a summary (a la pytest) with all broken links repeated would be useful.

A

[jayaddison]

Thanks @AA-Turner - there seem to be a few reports similar to this. One thing I'm still wondering about is: does the -q (quiet) flag to Sphinx provide an acceptable solution? (cc @Daltz333) -- and if so, perhaps we should make that more visible?

When quiet output is enabled, the linkcheck builder should output only the problematic links (and their source file/line locations) to the console, meaning that scrollback should be much reduced.

Here's an output from running against a local copy of sphinx v7.2.6 (59cf4d4):

$ make linkcheck SPHINXOPTS="-q"
/home/build/sphinx/doc/tutorial/end.rst:4: WARNING: broken link: ../contents.html ()
/home/build/sphinx/doc/index.rst:43: WARNING: broken link: contents.html ()
/home/build/sphinx/doc/examples.rst:449: WARNING: broken link: http://pioneers.rstebbing.com/ (Exceeded 30 redirects.)
/home/build/sphinx/doc/examples.rst:99: WARNING: broken link: http://sprox.org/ (HTTPConnectionPool(host='sprox.org', port=80): Max retries exceeded with url: / (Caused by NameResolutionError("<urllib3.connection.HTTPConnection object at 0x7fc0461e0f50>: Failed to resolve 'sprox.org' ([Errno -3] Temporary failure in name resolution)")))
/home/build/sphinx/doc/tutorial/deploying.rst:275: WARNING: broken link: https://about.gitlab.com/blog/2021/05/17/prevent-crypto-mining-abuse/#validating-an-account (Anchor 'validating-an-account' not found)
/home/build/sphinx/doc/examples.rst:72: WARNING: broken link: http://grok.zope.org/doc/current/ (HTTPConnectionPool(host='grok.zope.org', port=80): Read timed out. (read timeout=5))
/home/build/sphinx/doc/examples.rst:291: WARNING: broken link: https://docs.topshelf-project.com/ (HTTPSConnectionPool(host='docs.topshelf-project.com', port=443): Max retries exceeded with url: / (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7fc046105610>: Failed to establish a new connection: [Errno 111] Connection refused')))
/home/build/sphinx/doc/examples.rst:109: WARNING: broken link: https://docs.zope.org/zope2/ (404 Client Error: Not Found for url: https://www.zope.dev/zope2/)
/home/build/sphinx/doc/usage/restructuredtext/basics.rst:292: WARNING: broken link: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#roles (Anchor 'roles' not found)
/home/build/sphinx/doc/usage/extensions/napoleon.rst:43: WARNING: broken link: https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings (Anchor 'docstrings' not found)
/home/build/sphinx/doc/usage/extensions/autodoc.rst:38: WARNING: broken link: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings (Anchor '38-comments-and-docstrings' not found)
/home/build/sphinx/doc/tutorial/deploying.rst:130: WARNING: broken link: https://gitlab.com/projects/new (403 Client Error: Forbidden for url: https://gitlab.com/users/sign_in)
/home/build/sphinx/doc/tutorial/automatic-doc-generation.rst:162: WARNING: broken link: https://jinja2docs.readthedocs.io/ (404 Client Error: Not Found for url: https://jinja2docs.readthedocs.io/en/stable/)
/home/build/sphinx/doc/tutorial/deploying.rst:114: WARNING: broken link: https://lab.github.com/githubtraining/introduction-to-github (404 Client Error: Not Found for url: https://lab.github.com/githubtraining/introduction-to-github)
/home/build/sphinx/doc/examples.rst:387: WARNING: broken link: https://opendylan.org/ (HTTPSConnectionPool(host='opendylan.org', port=443): Max retries exceeded with url: / (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1006)'))))
/home/build/sphinx/doc/examples.rst:389: WARNING: broken link: https://openturns.github.io/openturns/master/ (404 Client Error: Not Found for url: https://openturns.github.io/openturns/master/)
/home/build/sphinx/doc/usage/installation.rst:202: WARNING: broken link: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment (Anchor 'creating-a-virtual-environment' not found)
/home/build/sphinx/doc/examples.rst:67: WARNING: broken link: https://pageperso.lif.univ-mrs.fr/~edouard.thiel/ez-draw/doc/en/html/ez-manual.html (HTTPSConnectionPool(host='pageperso.lif.univ-mrs.fr', port=443): Max retries exceeded with url: /~edouard.thiel/ez-draw/doc/en/html/ez-manual.html (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: certificate has expired (_ssl.c:1006)'))))
/home/build/sphinx/doc/development/builders.rst:9: WARNING: broken link: https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins (Anchor 'dynamic-discovery-of-services-and-plugins' not found)
/home/build/sphinx/doc/support.rst:4: WARNING: broken link: https://web.libera.chat/?channel=#sphinx-doc (Anchor 'sphinx-doc' not found)
/home/build/sphinx/doc/usage/installation.rst:62: WARNING: broken link: https://www.anaconda.com/download/#macos (Anchor 'macos' not found)
/home/build/sphinx/doc/examples.rst:118: WARNING: broken link: https://www.mdanalysis.org/MDAnalysisTutorial/ (404 Client Error: Not Found for url: https://www.mdanalysis.org/MDAnalysisTutorial/)
/home/build/sphinx/doc/examples.rst:360: WARNING: broken link: https://www.adobe.com/devnet-docs/acrobatetk/ (HTTPSConnectionPool(host='www.adobe.com', port=443): Read timed out. (read timeout=5))
/home/build/sphinx/doc/examples.rst:440: WARNING: broken link: https://www.packtpub.com/application-development/expert-python-programming (HTTPSConnectionPool(host='www.packtpub.com', port=443): Read timed out. (read timeout=5))
make: *** [Makefile:20: linkcheck] Error 1

(home directory paths changed, otherwise unedited)