Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Jonathan Corbet <corbet@lwn.net>
To:     linux-doc@vger.kernel.org
Cc:     linux-kernel@vger.kernel.org,
        =?UTF-8?q?N=C3=ADcolas=20F=20=2E=20R=20=2E=20A=20=2E=20Prado?= 
        <n@nfraprado.net>, Jonathan Corbet <corbet@lwn.net>
Subject: [PATCH 1/2] docs: automarkup: track failed cross-reference attempts
Date:   Thu, 30 Jun 2022 10:36:29 -0600
Message-Id: <20220630163630.714673-2-corbet@lwn.net>
In-Reply-To: <20220630163630.714673-1-corbet@lwn.net>
References: <20220630163630.714673-1-corbet@lwn.net>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

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.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/sphinx/automarkup.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index cc348b219fca..5b1f83e6192f 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/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
 
-- 
2.36.1