Close sphinx-doc#10112: extlinks: Disable hardcoded links detector by…

… default

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.

CHANGES

@@ -7,12 +7,17 @@ Dependencies
 Incompatible changes
 --------------------
 
+* #10112: extlinks: Disable hardcoded links detector by default
+
 Deprecated
 ----------
 
 Features added
 --------------
 
+* #10112: extlinks: Add :confval:`extlinks_detect_hardcoded_links` to enable
+  hardcoded links detector feature
+
 Bugs fixed
 ----------
 

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.4.1

sphinx/ext/extlinks.py

@@ -55,6 +55,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)
 
@@ -124,6 +127,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}

tests/roots/test-ext-extlinks-hardcoded-urls-multiple-replacements/conf.py

@@ -3,3 +3,4 @@
     'user': ('https://github.com/%s', '@%s'),
     'repo': ('https://github.com/%s', 'project %s'),
 }
+extlinks_detect_hardcoded_links = True

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

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()