docs: automarkup: track failed cross-reference attempts

The automarkup code tries to create a lot of cross-references that don't
exist.  Cross-reference lookups are expensive, especially in later versions
of Sphinx, so there is value in avoiding unnecessary ones.  Remember
attempts that failed and do not retry them.

This improves the htmldocs build time by 5-10% depending on the phase of
the moon and other factors.

Tested-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220630163630.714673-2-corbet@lwn.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/sphinx/automarkup.py

@@ -120,6 +120,16 @@ def markup_refs(docname, app, node):
         repl.append(nodes.Text(t[done:]))
     return repl
 
+#
+# Keep track of cross-reference lookups that failed so we don't have to
+# do them again.
+#
+failed_lookups = { }
+def failure_seen(target, reftype):
+    return (target + '::' + reftype) in failed_lookups
+def note_failure(target, reftype):
+    failed_lookups[target + '::' + reftype] = True
+
 #
 # In sphinx3 we can cross-reference to C macro and function, each one with its
 # own C role, but both match the same regex, so we try both.
@@ -145,6 +155,8 @@ def markup_func_ref_sphinx3(docname, app, match):
         for target in possible_targets:
             if target not in Skipfuncs:
                 for class_s, reftype_s in zip(class_str, reftype_str):
+                    if failure_seen(target, reftype_s):
+                        continue
                     lit_text = nodes.literal(classes=['xref', 'c', class_s])
                     lit_text += target_text
                     pxref = addnodes.pending_xref('', refdomain = 'c',
@@ -164,6 +176,7 @@ def markup_func_ref_sphinx3(docname, app, match):
 
                     if xref:
                         return xref
+                    note_failure(target, reftype_s)
 
     return target_text