fix: don't unlink roles that are explicit references

nedbat · nedbat · commit 58133020fb9e · 2026-03-10T05:33:10.000-04:00
diff --git a/README.rst b/README.rst
@@ -67,6 +67,14 @@ hard-code the decisions.
 Changes
 =======
 
+Unreleased
+----------
+
+A number of roles (``:ref:``, ``:doc:`` and others) were being unlinked when
+they seemed excessive, but shouldn't have been. They are explicit references to
+other parts of the documentation, so should never be removed. This is now
+fixed.
+
 v0.3.1 (2026-03-01)
 -------------------
 
diff --git a/src/linklint/linklint.py b/src/linklint/linklint.py
@@ -96,6 +96,9 @@ def decorator(func):
     ),
 ]
 
+# Sphinx roles that are explicit references elsewhere and should always be links.
+ALWAYS_REF = {"doc", "download", "numref", "ref"}
+
 
 @check("self")
 def check_self_links(work: LintWork) -> Iterable[LintIssue]:
@@ -135,6 +138,11 @@ def __init__(self, doctree: nodes.document) -> None:
     def visit_pending_xref(self, node: addnodes.pending_xref) -> None:
         line = node_line_number(node)
         reftype = node.get("reftype")
+        if reftype in ALWAYS_REF:
+            # :ref: references are explicitly meant to be links, so should
+            # never be unlinked. I don't know why someone would put a :ref:
+            # to its own section, but who are we to judge?
+            return
         target = node.get("reftarget")
 
         if reftype == "meth" and "." not in target:
@@ -199,6 +207,10 @@ def find_duplicate_refs(doctree: nodes.document) -> Iterable[nodes.Node]:
         refs_by_target = defaultdict(list)
         for ref in para.findall(addnodes.pending_xref):
             reftype = ref.get("reftype")
+            if reftype in ALWAYS_REF:
+                # :ref: references are explicitly meant to be links, so should
+                # never be unlinked.
+                continue
             target = ref.get("reftarget")
             assert reftype and target, (
                 f"Reference missing reftype or target: {ref}\n{node_traceback(ref)}"
diff --git a/tests/data/ref_references.rst b/tests/data/ref_references.rst
@@ -0,0 +1,13 @@
+Some docs
+=========
+
+You can specify a :ref:`static context <contexts>` for a coverage run with
+``--context``.  This can be any label you want, and will be recorded with the
+data.  See :ref:`contexts` for more information.
+
+.. _contexts:
+
+Measurement contexts
+--------------------
+
+They are important! This section is :ref:`contexts`.
diff --git a/tests/data/ref_references_summary.html b/tests/data/ref_references_summary.html
@@ -0,0 +1,32 @@
+<section id="some-docs">
+  <h1>
+    Some docs
+  </h1>
+  <p>
+    You can specify a
+    <a href="#contexts">
+      static context
+    </a>
+    for a coverage run with
+    <code>
+      --context
+    </code>
+    . This can be any label you want, and will be recorded with the data. See
+    <a href="#contexts">
+      Measurement contexts
+    </a>
+    for more information.
+  </p>
+  <section id="measurement-contexts">
+    <h2>
+      Measurement contexts
+    </h2>
+    <p>
+      They are important! This section is
+      <a href="#contexts">
+        Measurement contexts
+      </a>
+      .
+    </p>
+  </section>
+</section>
