Fix #6914: Emit a detailed warning when failed to resolve :ref:

To be clear the ambiguous warning for missing-reference :ref:,
this separates the warning to missing-label and missing-caption.

To emit a warning dynamically, this also adds a new event:
`warn-missing-reference` to customize warning messages via event
handlers.

1 files changed, 15 insertions, 2 deletions

diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py
index 39f67b54e..7ea468404 100644
--- a/sphinx/domains/std.py
+++ b/sphinx/domains/std.py
@@ -610,8 +610,6 @@ class StandardDomain(Domain):
 
     dangling_warnings = {
         'term': 'term not in glossary: %(target)s',
-        'ref':  'undefined label: %(target)s (if the link has no caption '
-                'the label must precede a section header)',
         'numref':  'undefined label: %(target)s',
         'keyword': 'unknown keyword: %(target)s',
         'doc': 'unknown document: %(target)s',
@@ -1107,8 +1105,23 @@ class StandardDomain(Domain):
                       RemovedInSphinx40Warning, stacklevel=2)
 
 
+def warn_missing_reference(app: "Sphinx", domain: Domain, node: pending_xref) -> bool:
+    if domain.name != 'std' or node['reftype'] != 'ref':
+        return None
+    else:
+        target = node['reftarget']
+        if target not in domain.anonlabels:  # type: ignore
+            msg = __('undefined label: %s')
+        else:
+            msg = __('Failed to create a cross reference. A title or caption not found: %s')
+
+        logger.warning(msg % target, location=node, type='ref', subtype=node['reftype'])
+        return True
+
+
 def setup(app: "Sphinx") -> Dict[str, Any]:
     app.add_domain(StandardDomain)
+    app.connect('warn-missing-reference', warn_missing_reference)
 
     return {
         'version': 'builtin',