linkcheck builder: add 'linkcheck_distinguish_timeouts' config option

[jayaddison]

Feature or Bugfix

• Feature (adjustment)

Purpose

• Makes the distinct linkcheck status code for timeout opt-in instead of always-enabled.
• I've been worrying about potential downstream linkchecker-reporting problems if we enable this silently; this provides a migration path.

Detail

• Adds a default-disabled linkcheck_distinguish_timeouts configuratin option.

Relates

• Follow-up to #11876.

[jayaddison]

I'm not fan of the configuration name but I don't have a better one

Yep, it took me a while to decide, and doesn't seem perfect to me either. I think linkcheck_report_timeouts was one of the other similar-quality candidates (but could kind-of imply that we don't report timed-out hyperlinks as problems when it's disabled..).

[jayaddison]

I think that merging this would hide the problem reported in #12038 -- so I think we should try to figure out the problem there beforehand.

[jayaddison]

I think that merging this would hide the problem reported in #12038 -- so I think we should try to figure out the problem there beforehand.

...with one exception to that rule: if we have not resolved that problem by the time that a 7.3.0 release is planned, then we should merge this to retain backwards-compatible behaviour by default.

[jayaddison]

No, sorry, I'm talking nonsense. The affected test doesn't only check the link status, it also checks for a specific SSL-related failure message. False alarm.

[picnixz]

if we have not resolved that problem by the time that a 7.3.0 release is planned,

Problem before that is that I don't know when 7.3 is planned. I'm not sure I can do it myself since I only have perms on github directly.

[picnixz]

Since I have time in the train, here are some alternatives:

• linkcheck_discriminate_timeout (defaults False)
• linkcheck_explicit_timeout (defaults False)
• linkcheck_explicit_errors (defaults False) which could be used in the future if we want to have different report status based on HTTP error codes or something else, instead of gobbling them in the "broken" status. I kinda like this one because it's not just for timeout but also if the host is offline for instance.

[picnixz]

Btw, maybe add some doc for that?

[AA-Turner]

I've renamed the option to linkcheck_report_timeouts_as_broken, which is clearer, though a logical inversion. The question is if this is removed in Sphinx 8, or simply has the default changed to False.

A