From nobody Sun Apr 19 13:44:18 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id AF5F0C433EF for ; Thu, 30 Jun 2022 16:37:04 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S236016AbiF3QhC (ORCPT ); Thu, 30 Jun 2022 12:37:02 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42818 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236026AbiF3QhA (ORCPT ); Thu, 30 Jun 2022 12:37:00 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id EA5953B55F; Thu, 30 Jun 2022 09:36:59 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 82ADE2BD; Thu, 30 Jun 2022 16:36:59 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 82ADE2BD DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1656607019; bh=iUgBxaMFogHblUjqh3+L/kIHthcIN9dVA3xUYz0iqas=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=psgMGBO74DasMyPGIUlPkemb+ZFWEqiUsKUtazCQZy+BbRa0iJb/3+Hy1Qjo0zoAM jQf3ga0moFUJOILhDt2K2KZKnd8tpjAs5a8jMum5IRqHS0KIluCgQSyViGjvo06Vb6 3qwexoMVJrKBjGi182S3u4tV792NmPOno127BzPXq4IO5abhj7qFbywuFyanbvPK0A oQyJzsTRAS1sS2/fgSzC9RtI+wrdtsyU624JDrMMt6WG3EwGXaNQ7ayNU7PiEOHCAQ igiDahmQRmFfYRNK20wZ18UqOiP1JLLgKvHmhQqAdwDn7XL4gXV3ys2WkCg1BrKHB7 cZjwIwj9dJZTQ== From: Jonathan Corbet 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?= , Jonathan Corbet 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> X-Mailer: git-send-email 2.36.1 In-Reply-To: <20220630163630.714673-1-corbet@lwn.net> References: <20220630163630.714673-1-corbet@lwn.net> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" 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 Tested-by: Akira Yokosawa --- Documentation/sphinx/automarkup.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/auto= markup.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 =20 +# +# Keep track of cross-reference lookups that failed so we don't have to +# do them again. +# +failed_lookups =3D { } +def failure_seen(target, reftype): + return (target + '::' + reftype) in failed_lookups +def note_failure(target, reftype): + failed_lookups[target + '::' + reftype] =3D 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 =3D nodes.literal(classes=3D['xref', 'c', cla= ss_s]) lit_text +=3D target_text pxref =3D addnodes.pending_xref('', refdomain =3D 'c', @@ -164,6 +176,7 @@ def markup_func_ref_sphinx3(docname, app, match): =20 if xref: return xref + note_failure(target, reftype_s) =20 return target_text =20 --=20 2.36.1 From nobody Sun Apr 19 13:44:18 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id B0081C433EF for ; Thu, 30 Jun 2022 16:37:11 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S235802AbiF3QhK (ORCPT ); Thu, 30 Jun 2022 12:37:10 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42834 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236181AbiF3QhB (ORCPT ); Thu, 30 Jun 2022 12:37:01 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 4FE4D3BA41; Thu, 30 Jun 2022 09:37:00 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id E002760B; Thu, 30 Jun 2022 16:36:59 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E002760B DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1656607020; bh=NJ/Y9ONMRQjKnuqNr+P82fP9Qj+0laPsAzZtOD+ZrsU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nto3tl8ZDBazIuSqbrwftEdcHKIgLAuEaNjBqWKDlgchLQVneCBtJ3/zi0YttVWSz OTY7RoLhxENDankyDZogHTU9VccuKR+LukqH/MPEZSNYGny3NVhnYCD3q9pu7jIptr c8BHloTXR5Tgu90eusYF02fZ3KXbbJJYIurMJNvC7GkDDgfOU9CMbLk+JdQkIppnNn XU5sXA2ZeobEhQJ4ADaxXINw5rf0v1emH+jNJ6/tUQupovXPIkudcyCDFgpOaMfns8 8cYhZG/HF7OswJmABTr/XPIKjQOKA+VtamTQ1ROKvKr9c+G4QibFMyA4eJZ7tmYPMH kYYJm4J0pbw2g== From: Jonathan Corbet 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?= , Jonathan Corbet Subject: [PATCH 2/2] docs: automarkup: do not look up symbols twice Date: Thu, 30 Jun 2022 10:36:30 -0600 Message-Id: <20220630163630.714673-3-corbet@lwn.net> X-Mailer: git-send-email 2.36.1 In-Reply-To: <20220630163630.714673-1-corbet@lwn.net> References: <20220630163630.714673-1-corbet@lwn.net> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" The automarkup code tries to look up symbols once as a function, and once as a macro. The Sphinx C domain code, though, totally ignores that distinction and will return the same results either way. So just look things up once and be done with it; the resulting output does not change, but htmldocs build time drops by about 5%. Signed-off-by: Jonathan Corbet Tested-by: Akira Yokosawa --- Documentation/sphinx/automarkup.py | 57 ++++++++++++++---------------- 1 file changed, 26 insertions(+), 31 deletions(-) diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/auto= markup.py index 5b1f83e6192f..06b34740bf90 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -125,19 +125,16 @@ def markup_refs(docname, app, node): # do them again. # failed_lookups =3D { } -def failure_seen(target, reftype): - return (target + '::' + reftype) in failed_lookups -def note_failure(target, reftype): - failed_lookups[target + '::' + reftype] =3D True +def failure_seen(target): + return (target) in failed_lookups +def note_failure(target): + failed_lookups[target] =3D True =20 # # 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. # def markup_func_ref_sphinx3(docname, app, match): - class_str =3D ['c-func', 'c-macro'] - reftype_str =3D ['function', 'macro'] - cdom =3D app.env.domains['c'] # # Go through the dance of getting an xref out of the C domain @@ -153,30 +150,28 @@ def markup_func_ref_sphinx3(docname, app, match): =20 if base_target not in Skipnames: 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 =3D nodes.literal(classes=3D['xref', 'c', cla= ss_s]) - lit_text +=3D target_text - pxref =3D addnodes.pending_xref('', refdomain =3D 'c', - reftype =3D reftype_s, - reftarget =3D target, mo= dname =3D None, - classname =3D None) - # - # XXX The Latex builder will throw NoUri exceptions he= re, - # work around that by ignoring them. - # - try: - xref =3D cdom.resolve_xref(app.env, docname, app.b= uilder, - reftype_s, target, pxref, - lit_text) - except NoUri: - xref =3D None - - if xref: - return xref - note_failure(target, reftype_s) + if (target not in Skipfuncs) and not failure_seen(target): + lit_text =3D nodes.literal(classes=3D['xref', 'c', 'c-func= ']) + lit_text +=3D target_text + pxref =3D addnodes.pending_xref('', refdomain =3D 'c', + reftype =3D 'function', + reftarget =3D target, + modname =3D None, + classname =3D None) + # + # XXX The Latex builder will throw NoUri exceptions here, + # work around that by ignoring them. + # + try: + xref =3D cdom.resolve_xref(app.env, docname, app.build= er, + 'function', target, pxref, + lit_text) + except NoUri: + xref =3D None + + if xref: + return xref + note_failure(target) =20 return target_text =20 --=20 2.36.1