Close #10125: extlinks: Improve suggestion message for a reference having title

1 files changed, 7 insertions, 2 deletions

diff --git a/sphinx/ext/extlinks.py b/sphinx/ext/extlinks.py
index a14c396b6..8caba8842 100644
--- a/sphinx/ext/extlinks.py
+++ b/sphinx/ext/extlinks.py
@@ -38,7 +38,7 @@ from sphinx.application import Sphinx
 from sphinx.deprecation import RemovedInSphinx60Warning
 from sphinx.locale import __
 from sphinx.transforms.post_transforms import SphinxPostTransform
-from sphinx.util import logging
+from sphinx.util import logging, rst
 from sphinx.util.nodes import split_explicit_title
 from sphinx.util.typing import RoleFunction
 
@@ -67,6 +67,7 @@ class ExternalLinksChecker(SphinxPostTransform):
             return
 
         uri = refnode['refuri']
+        title = refnode.astext()
 
         for alias, (base_uri, _caption) in self.app.config.extlinks.items():
             uri_pattern = re.compile(base_uri.replace('%s', '(?P<value>.+)'))
@@ -75,7 +76,11 @@ class ExternalLinksChecker(SphinxPostTransform):
                 # build a replacement suggestion
                 msg = __('hardcoded link %r could be replaced by an extlink '
                          '(try using %r instead)')
-                replacement = f":{alias}:`{match.groupdict().get('value')}`"
+                value = match.groupdict().get('value')
+                if uri != title:
+                    replacement = f":{alias}:`{rst.escape(title)} <{value}>`"
+                else:
+                    replacement = f":{alias}:`{value}`"
                 logger.warning(msg, uri, replacement, location=refnode)