linkcheck: Make the new 'timeout' status opt-in (#12023)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

CHANGES.rst

@@ -108,6 +108,8 @@ Bugs fixed
   responses as broken.
   Patch by James Addison.
 * #11868: linkcheck: added a distinct ``timeout`` reporting status code.
+  This can be enabled by setting :confval:`linkcheck_report_timeouts_as_broken`
+  to ``False``.
   Patch by James Addison.
 * #11869: Refresh the documentation for the ``linkcheck_timeout`` setting.
   Patch by James Addison.

doc/usage/configuration.rst

@@ -2971,6 +2971,21 @@ Options for the linkcheck builder
 
    .. versionadded:: 7.3
 
+.. confval:: linkcheck_report_timeouts_as_broken
+
+   When an HTTP response is not received from a webserver before the configured
+   :confval:`linkcheck_timeout` expires,
+   the current default behaviour of Sphinx is to treat the link as 'broken'.
+   To report timeouts using a distinct report code of ``timeout``,
+   set :confval:`linkcheck_report_timeouts_as_broken` to ``False``.
+
+   From Sphinx 8.0 onwards, timeouts that occur while checking hyperlinks
+   will be reported using the new 'timeout' status code.
+
+   .. xref RemovedInSphinx80Warning
+
+   .. versionadded:: 7.3
+
 
 Options for the XML builder
 ---------------------------

sphinx/builders/linkcheck.py

@@ -75,6 +75,16 @@ class CheckExternalLinksBuilder(DummyBuilder):
             )
             warnings.warn(deprecation_msg, RemovedInSphinx80Warning, stacklevel=1)
 
+        if self.config.linkcheck_report_timeouts_as_broken:
+            deprecation_msg = (
+                "The default value for 'linkcheck_report_timeouts_as_broken' will change "
+                'to False in Sphinx 8, meaning that request timeouts '
+                "will be reported with a new 'timeout' status, instead of as 'broken'. "
+                'This is intended to provide more detail as to the failure mode. '
+                'See https://github.com/sphinx-doc/sphinx/issues/11868 for details.'
+            )
+            warnings.warn(deprecation_msg, RemovedInSphinx80Warning, stacklevel=1)
+
     def finish(self) -> None:
         checker = HyperlinkAvailabilityChecker(self.config)
         logger.info('')
@@ -302,6 +312,10 @@ class HyperlinkAvailabilityCheckWorker(Thread):
         self.retries: int = config.linkcheck_retries
         self.rate_limit_timeout = config.linkcheck_rate_limit_timeout
         self._allow_unauthorized = config.linkcheck_allow_unauthorized
+        if config.linkcheck_report_timeouts_as_broken:
+            self._timeout_status = 'broken'
+        else:
+            self._timeout_status = 'timeout'
 
         self.user_agent = config.user_agent
         self.tls_verify = config.tls_verify
@@ -444,7 +458,7 @@ class HyperlinkAvailabilityCheckWorker(Thread):
                 break
 
             except RequestTimeout as err:
-                return 'timeout', str(err), 0
+                return self._timeout_status, str(err), 0
 
             except SSLError as err:
                 # SSL failure; report that the link is broken.
@@ -669,6 +683,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_config_value('linkcheck_anchors_ignore_for_url', (), '', (tuple, list))
     app.add_config_value('linkcheck_rate_limit_timeout', 300.0, '')
     app.add_config_value('linkcheck_allow_unauthorized', True, '')
+    app.add_config_value('linkcheck_report_timeouts_as_broken', True, '', bool)
 
     app.add_event('linkcheck-process-uri')
 

tests/test_builders/test_build_linkcheck.py

@@ -856,7 +856,13 @@ def test_too_many_requests_retry_after_without_header(app, capsys):
     )
 
 
-@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver', freshenv=True)
+@pytest.mark.sphinx(
+    'linkcheck', testroot='linkcheck-localserver', freshenv=True,
+    confoverrides={
+        'linkcheck_report_timeouts_as_broken': False,
+        'linkcheck_timeout': 0.01,
+    }
+)
 def test_requests_timeout(app):
     class DelayedResponseHandler(BaseHTTPRequestHandler):
         protocol_version = "HTTP/1.1"
@@ -867,7 +873,6 @@ def test_requests_timeout(app):
             self.send_header("Content-Length", "0")
             self.end_headers()
 
-    app.config.linkcheck_timeout = 0.01
     with serve_application(app, DelayedResponseHandler):
         app.build()