From nobody Sun Feb 8 10:16:15 2026 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 1A9AC28ECE9; Wed, 4 Jun 2025 14:37:18 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749047841; cv=none; b=e/i84inXcW9E/wdRpw9LuIhG89wIfhS+0T9CW2QU9YzBy0Dwiz9OjJEXkyI9r/zlaH3jumYXOxTpEeejQJ56hquASOGnm89UWOP7uuoMuxf0gBHvcCXn8ElLoUiMmen+0GO0MywupcrDvWuEe3tn0ADNF9dI4YPwaLQrXeEz3ec= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749047841; c=relaxed/simple; bh=o/eS0IF6n81//MErCyau1coRDfnLuZuoMMa9zXVwLg0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=koPhM67n+Msp1sIrbF68JqaCviKDzq+IGN2YTBWH2R0QmTKSFhelBrb334h3seMqJM6XsRADhCxH2OwL6pCSRM9/3eFMerGcNP2PwtTidM/rG5mMbr+n0IoV9tW3PuSVczRabtHsrSY/gBrWcRfoxnWza8Qt6d7ji5jdXTSs864= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=VWhgABLz; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="VWhgABLz" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 2485541F28 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1749047838; bh=wNJhZW6ihKPzqnGzsjX01EfMfrNUVHiRICJcUri79Tc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=VWhgABLzPv5K191kbMmASTQ4FJhxOc93Wb0ofcM+VzBxGSI9IhJWJgus1vlJbgO3f +ezPU8nDNiyyEfi0FoBpaI+3MMb9ctJOVqkwwG+OnmwWVw+A/BGZFb/cQYN6FaghaS Au58jdselallcC7zVGKNunPxXJAfAxqKPEHfBW2PvkIaqIRJnTJEgItLEajxloRttt AHpCUl5tAYm9ZtGcdoKGIkBEe5DRnjFHZ3dP7BpbIU1WQZ+1WgP6bHbgzYHab/mwa5 vL/b7osrDH7R7u9UExP6iFPPk2W/hWot5cXrjzM1Nt+L3Npnq4INA0zjUexrQyO/yE AdEvE+3cnd9Ww== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 2485541F28; Wed, 4 Jun 2025 14:37:18 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , =?UTF-8?q?N=C3=ADcolas=20F=2E=20R=2E=20A=2E=20Prado?= , Jonathan Corbet Subject: [PATCH v2 1/3] docs: automarkup: Remove some Sphinx 2 holdovers Date: Wed, 4 Jun 2025 08:36:43 -0600 Message-ID: <20250604143645.78367-2-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250604143645.78367-1-corbet@lwn.net> References: <20250604143645.78367-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Remove a few declarations that are no longer doing anything now that we have left Sphinx 2 behind. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab Reviewed-by: N=C3=ADcolas F. R. A. Prado Tested-by: N=C3=ADcolas F. R. A. Prado --- v2: Remove RE_generic_type as suggested by Mauro Documentation/sphinx/automarkup.py | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/auto= markup.py index fd633f7a0bc3..7828aeac92e7 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -22,12 +22,6 @@ from kernel_abi import get_kernel_abi # RE_function =3D re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=3Dre.ASCII) =20 -# -# Sphinx 2 uses the same :c:type role for struct, union, enum and typedef -# -RE_generic_type =3D re.compile(r'\b(struct|union|enum|typedef)\s+([a-zA-Z_= ]\w+)', - flags=3Dre.ASCII) - # # Sphinx 3 uses a different C role for each one of struct, union, enum and # typedef @@ -150,20 +144,12 @@ def markup_func_ref_sphinx3(docname, app, match): return target_text =20 def markup_c_ref(docname, app, match): - class_str =3D {# Sphinx 2 only - RE_function: 'c-func', - RE_generic_type: 'c-type', - # Sphinx 3+ only - RE_struct: 'c-struct', + class_str =3D {RE_struct: 'c-struct', RE_union: 'c-union', RE_enum: 'c-enum', RE_typedef: 'c-type', } - reftype_str =3D {# Sphinx 2 only - RE_function: 'function', - RE_generic_type: 'type', - # Sphinx 3+ only - RE_struct: 'struct', + reftype_str =3D {RE_struct: 'struct', RE_union: 'union', RE_enum: 'enum', RE_typedef: 'type', --=20 2.49.0 From nobody Sun Feb 8 10:16:15 2026 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 404412918E6; Wed, 4 Jun 2025 14:37:19 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749047841; cv=none; b=eo93+rwIUMF6OvpNr+HqspbXeHI47O6e8YeBuZwCjAQN1zCE00fZcJhzUHBDCWTjfb/ffZZICjE+y4wVKXyz9aTrSmwWYnNnUlN7Z1xIsyL5BpoV9F5tGR9m1EbTZoKMxsX3+p735kvyRczKJ4qcbiw8p1zZ+rYRV9LeSQMq000= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749047841; c=relaxed/simple; bh=xr4uTdRiZCNdMn3W5qWwwPpYDscXYuir3me+H8XQdC8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=I3eyZ7wLPywXcmZHrxGGhXXpFPPcK5f1jqClPAYefV3KqMdcssP3NmgMdd5Vgrbhusf9DLfLz3v7ZHLfereU1aX3abQUlXk4KN8yB438FgNGnHfT40heQT/75fOfu/v6eUFni+XLVrgAn/Cd5PBCoE+5nyFxMw6Mc1pcTPPlSBg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=iTEIGDQ8; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="iTEIGDQ8" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net A54A441F2A DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1749047839; bh=lQCobccnQ6ihUHwgNMz6oxJnLailFhApTPbx4Ru7zAA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iTEIGDQ8EuL9sG1212muriZArVDE7cLPYUI4khVzmAqhIQiD6wxTsm7BavqVwXaS1 WIJ0chjYgqQjFbQUeB7ZSp35XJ6epRGR2Q9i/Js3XpETm+KPlRFoDxJ6VdPKj0seHV rHGZN1ct9xEHIF6gIymoGKSUqFoPVO+UTM7/D0kKBtPzy05NWfoSU6ObH19GSEkoKm fZoCKMOJ12FgoUTom5CsMw0+lffXEZEWY7Y0Q94RJnspP3X7ezLHGLfAY92EOy9Ixw fSgQz8ZDC7lBznw7IulEMlfcszDHiExmuW/h5vYWNNKto0tlO1gqGmxD/RMnqA2vXS 9IBf2WRFNhYgw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id A54A441F2A; Wed, 4 Jun 2025 14:37:18 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , =?UTF-8?q?N=C3=ADcolas=20F=2E=20R=2E=20A=2E=20Prado?= , Jonathan Corbet Subject: [PATCH v2 2/3] docs: automarkup: Mark up undocumented entities too Date: Wed, 4 Jun 2025 08:36:44 -0600 Message-ID: <20250604143645.78367-3-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250604143645.78367-1-corbet@lwn.net> References: <20250604143645.78367-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The automarkup code generates markup and a cross-reference link for functions, structs, etc. for which it finds kerneldoc documentation. Undocumented entities are left untouched; that creates an inconsistent reading experience and has caused some writers to go to extra measures to cause the markup to happen. Mark up detected C entities regardless of whether they are documented. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab Reviewed-by: N=C3=ADcolas F. R. A. Prado Tested-by: N=C3=ADcolas F. R. A. Prado --- v2: Split out the CSS changes into a separate patch Documentation/sphinx/automarkup.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/auto= markup.py index 7828aeac92e7..e67eb8e19c22 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -235,8 +235,13 @@ def add_and_resolve_xref(app, docname, domain, reftype= , target, contnode=3DNone): =20 if xref: return xref - - return None + # + # We didn't find the xref; if a container node was supplied, + # mark it as a broken xref + # + if contnode: + contnode.set_class("broken_xref") + return contnode =20 # # Variant of markup_abi_ref() that warns whan a reference is not found --=20 2.49.0 From nobody Sun Feb 8 10:16:15 2026 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 404B02918EA; Wed, 4 Jun 2025 14:37:20 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749047841; cv=none; b=cYI7yhERDGgua829TcvkY6BFHYlS0FeaeaqYf+udXP98JsxPJEzrQbmf/wQluUleASnjmjJX/FVDRnYTO7SPwtXq4QtHMSw8Kczefncp+zNhUL4gey6wThFil2vGiN1PXrxDgkw0sL6NnSDNQObWn/2r7Eljqkes5SQWHdzXnps= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749047841; c=relaxed/simple; bh=n3BGNRF566cDDtcBKyLEimgg5xUVaSyHoq2hq+IcLis=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=gw34rn+rvcz6xvHzTzm0MPBDBlXtToLrWek+CUqnjFwG18phsRJGP6GhwvXjNK6KCG3cvyMvQfxQ+jec2ETf2tmiXwhCP/iBptU8yGda0D2PaMZXaASP/zEkKYCL9oIr10UwZmD+7y0Ejm3B4zDdgqPqK3ToNELDD3+LZ9SVJB4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=IoSaMw3J; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="IoSaMw3J" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 3CD6F41F2B DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1749047839; bh=tvFya/pb+S/tzuJ3dPBYB53ab6U3mH5GgVpq+XIb2Xk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=IoSaMw3J6td/EUscFMxtpKj5c4L75mCm4yXHrPDIapZbjHa78djnFsPezt1Wkowa1 6VyBX8st74kWI0au9OaGmZ7Cffd9ke4fqcXYe/gIvPndy/HXECmXwAvidrokXvYqU3 7o1803cKHsTaBc7Fb1gdDQ5tkDKZgKwim5A/lllO1Tr6feil1MLBaJjPS4rA8CI8Wp xO0XQc4SFmFcqqNANhUkoy8FnnMMezrv9XSDeJ9AZx0wpWrt4KMDckBd92TCoEs8tj zlSCdPCFwGTbnKkhrIqy0/KaCnG11T8CPYnMixrkjZ8HVO0MbBImLrM5tqRyinFvU+ 8XWkzsusX2r6w== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 3CD6F41F2B; Wed, 4 Jun 2025 14:37:19 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , =?UTF-8?q?N=C3=ADcolas=20F=2E=20R=2E=20A=2E=20Prado?= , Jonathan Corbet Subject: [PATCH v2 3/3] docs: CSS: make cross-reference links more evident Date: Wed, 4 Jun 2025 08:36:45 -0600 Message-ID: <20250604143645.78367-4-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250604143645.78367-1-corbet@lwn.net> References: <20250604143645.78367-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable The Sphinx Alabaster theme uses border-bottom to mark reference links; the result does not render correctly (the underline is missing) in some browser configurations. Switch to using the standard text-underline property, and use text-underline-offset to place that underline below any underscores in the underlined text. Suggested-by: N=C3=ADcolas F. R. A. Prado Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab Reviewed-by: N=C3=ADcolas F. R. A. Prado Tested-by: N=C3=ADcolas F. R. A. Prado --- Documentation/sphinx-static/custom.css | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-= static/custom.css index f4285417c71a..c9991566f914 100644 --- a/Documentation/sphinx-static/custom.css +++ b/Documentation/sphinx-static/custom.css @@ -136,3 +136,10 @@ div.language-selection:hover ul { div.language-selection ul li:hover { background: #dddddd; } + +/* Make xrefs more universally visible */ +a.reference, a.reference:hover { + border-bottom: none; + text-decoration: underline; + text-underline-offset: 0.3em; +} --=20 2.49.0