On Tue, May 30, 2023 at 07:02:26AM -0600, Jonathan Corbet wrote:

Conor Dooley [off-list ref] writes:

quoted

diff --git a/Documentation/devicetree/bindings/ABI.rst b/Documentation/devicetree/bindings/ABI.rst
index a885713cf184..93ec82f78ae5 100644
--- a/Documentation/devicetree/bindings/ABI.rst
+++ b/Documentation/devicetree/bindings/ABI.rst

@@ -1,5 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0
 
+.. _devicetree-abi:

Somehow we've developed this habit of putting labels at the top of each
file; I really think that they just add clutter and are best left out.
Without the label, this reference:

quoted

+Perhaps one of the most important things to highlight is that dt-bindings
+document the ABI between the devicetree and the kernel. Please see
+:ref:`devicetree-abi` more information on the ABI.

...can just be written as "Please see
Documentation/devicetree/bindings/ABI.rst".  The cross-reference link
will be generated as expected, and readers of the plain-text docs don't
have to go grepping to find the reference.

Sure. As someone who does read these things in their editor that sounds
preferable to me. I didn't know that I could do that, as the whole
"building the docs" thing is new to me ;)
I'll wait a bit before resubmitting for obvious reasons.

Cheers,
Conor.