extlinks: Disable hardcoded links detector by default (refs: #10126)

The hardcoded links detector added since 4.4.0 causes troubles in many
projects.  Therefore, this disables it by default, and adds a new
configuration `extlinks_detect_hardcoded_links` to enable it explicitly.

6 files changed, 26 insertions, 0 deletions

diff --git a/CHANGES b/CHANGES
index 02c8ab307..17606bd73 100644
--- a/CHANGES
+++ b/CHANGES
@@ -7,6 +7,8 @@ Dependencies
 Incompatible changes
 --------------------
 
+* #10112: extlinks: Disable hardcoded links detector by default
+
 Deprecated
 ----------
 
@@ -18,6 +20,8 @@ Features added
 * #10260: Enable ``FORCE_COLOR`` and ``NO_COLOR`` for terminal colouring
 * #10234: autosummary: Add "autosummary" CSS class to summary tables
 * #10125: extlinks: Improve suggestion message for a reference having title
+* #10112: extlinks: Add :confval:`extlinks_detect_hardcoded_links` to enable
+  hardcoded links detector feature
 * #9494, #9456: html search: Add a config variable
   :confval:`html_show_search_summary` to enable/disable the search summaries
 * #9337: HTML theme, add option ``enable_search_shortcuts`` that enables :kbd:'/' as
diff --git a/doc/usage/extensions/extlinks.rst b/doc/usage/extensions/extlinks.rst
index c345a7c82..97359aba5 100644
--- a/doc/usage/extensions/extlinks.rst
+++ b/doc/usage/extensions/extlinks.rst
@@ -59,3 +59,11 @@ The extension adds a config value:
 
    Since links are generated from the role in the reading stage, they appear as
    ordinary links to e.g. the ``linkcheck`` builder.
+
+.. confval:: extlinks_detect_hardcoded_links
+
+   If enabled, extlinks emits a warning if a hardcoded link is replaceable
+   by an extlink, and suggests a replacement via warning.  It defaults to
+   ``False``.
+
+   .. versionadded:: 4.5
diff --git a/sphinx/ext/extlinks.py b/sphinx/ext/extlinks.py
index 4b476ec0a..b012c0f96 100644
--- a/sphinx/ext/extlinks.py
+++ b/sphinx/ext/extlinks.py
@@ -47,6 +47,9 @@ class ExternalLinksChecker(SphinxPostTransform):
     default_priority = 500
 
     def run(self, **kwargs: Any) -> None:
+        if not self.config.extlinks_detect_hardcoded_links:
+            return
+
         for refnode in self.document.findall(nodes.reference):
             self.check_uri(refnode)
 
@@ -121,6 +124,8 @@ def setup_link_roles(app: Sphinx) -> None:
 
 def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('extlinks', {}, 'env')
+    app.add_config_value('extlinks_detect_hardcoded_links', False, 'env')
+
     app.connect('builder-inited', setup_link_roles)
     app.add_post_transform(ExternalLinksChecker)
     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
diff --git a/tests/roots/test-ext-extlinks-hardcoded-urls-multiple-replacements/conf.py b/tests/roots/test-ext-extlinks-hardcoded-urls-multiple-replacements/conf.py
index f97077300..f46344971 100644
--- a/tests/roots/test-ext-extlinks-hardcoded-urls-multiple-replacements/conf.py
+++ b/tests/roots/test-ext-extlinks-hardcoded-urls-multiple-replacements/conf.py
@@ -3,3 +3,4 @@ extlinks = {
     'user': ('https://github.com/%s', '@%s'),
     'repo': ('https://github.com/%s', 'project %s'),
 }
+extlinks_detect_hardcoded_links = True
diff --git a/tests/roots/test-ext-extlinks-hardcoded-urls/conf.py b/tests/roots/test-ext-extlinks-hardcoded-urls/conf.py
index 0fa9f8c76..db0b3410f 100644
--- a/tests/roots/test-ext-extlinks-hardcoded-urls/conf.py
+++ b/tests/roots/test-ext-extlinks-hardcoded-urls/conf.py
@@ -1,2 +1,3 @@
 extensions = ['sphinx.ext.extlinks']
 extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s', 'issue %s')}
+extlinks_detect_hardcoded_links = True
diff --git a/tests/test_ext_extlinks.py b/tests/test_ext_extlinks.py
index 9b0e96cb0..0e257364e 100644
--- a/tests/test_ext_extlinks.py
+++ b/tests/test_ext_extlinks.py
@@ -1,6 +1,13 @@
 import pytest
 
 
+@pytest.mark.sphinx('html', testroot='ext-extlinks-hardcoded-urls',
+                    confoverrides={'extlinks_detect_hardcoded_links': False})
+def test_extlinks_detect_candidates(app, warning):
+    app.build()
+    assert warning.getvalue() == ''
+
+
 @pytest.mark.sphinx('html', testroot='ext-extlinks-hardcoded-urls')
 def test_replaceable_uris_emit_extlinks_warnings(app, warning):
     app.build()