[PATCH 0/9] Extend automarkup support for ABI symbols

[PATCH 0/9] Extend automarkup support for ABI symbols

[Mauro Carvalho Chehab]

Now that ABI creates a python dictionary, use automarkup to create cross
references for ABI symbols as well. 

Mauro Carvalho Chehab (9):
  docs: media: Allow creating cross-references for RC ABI
  docs: automarkup: drop legacy support
  docs: thunderbolt: Allow creating cross-references for ABI
  docs: arm: asymmetric-32bit: Allow creating cross-references for ABI
  docs: arm: generic-counter: Allow creating cross-references for ABI
  docs: iio: Allow creating cross-references ABI
  docs: networking: Allow creating cross-references statistics ABI
  docs: submit-checklist: Allow creating cross-references for ABI README
  docs: translations: Allow creating cross-references for ABI README

 Documentation/admin-guide/thunderbolt.rst     |  2 +-
 Documentation/arch/arm64/asymmetric-32bit.rst |  2 +-
 Documentation/driver-api/generic-counter.rst  |  4 +-
 Documentation/driver-api/iio/core.rst         |  2 +-
 Documentation/iio/iio_devbuf.rst              |  2 +-
 Documentation/networking/statistics.rst       |  2 +-
 Documentation/process/submit-checklist.rst    |  2 +-
 Documentation/sphinx/automarkup.py            | 47 ++++++++-----------
 .../it_IT/process/submit-checklist.rst        |  2 +-
 .../sp_SP/process/submit-checklist.rst        |  2 +-
 .../zh_CN/process/submit-checklist.rst        |  2 +-
 .../zh_TW/process/submit-checklist.rst        |  2 +-
 .../userspace-api/media/rc/rc-sysfs-nodes.rst |  2 +-
 13 files changed, 32 insertions(+), 41 deletions(-)

-- 
2.48.1

[PATCH 1/9] docs: media: Allow creating cross-references for RC ABI

[Mauro Carvalho Chehab]

Now that Documentation/ABI is processed by automarkup, let it
generate cross-references for RC sysfs devnodes.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/automarkup.py              | 17 +++++++++++++----
 .../userspace-api/media/rc/rc-sysfs-nodes.rst   |  2 +-
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 22defc18d6d2..03bb7020f5cb 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -88,13 +88,13 @@ def markup_refs(docname, app, node):
     # Associate each regex with the function that will markup its matches
     #
     markup_func_sphinx2 = {RE_doc: markup_doc_ref,
-                           RE_abi_file: markup_abi_ref,
+                           RE_abi_file: markup_abi_file_ref,
                            RE_abi_symbol: markup_abi_ref,
                            RE_function: markup_c_ref,
                            RE_generic_type: markup_c_ref}
 
     markup_func_sphinx3 = {RE_doc: markup_doc_ref,
-                           RE_abi_file: markup_abi_ref,
+                           RE_abi_file: markup_abi_file_ref,
                            RE_abi_symbol: markup_abi_ref,
                            RE_function: markup_func_ref_sphinx3,
                            RE_struct: markup_c_ref,
@@ -279,10 +279,10 @@ def markup_doc_ref(docname, app, match):
         return nodes.Text(match.group(0))
 
 #
-# Try to replace a documentation reference of the form Documentation/ABI/...
+# Try to replace a documentation reference for ABI symbols and files
 # with a cross reference to that page
 #
-def markup_abi_ref(docname, app, match):
+def markup_abi_ref(docname, app, match, warning=False):
     stddom = app.env.domains['std']
     #
     # Go through the dance of getting an xref out of the std domain
@@ -294,6 +294,8 @@ def markup_abi_ref(docname, app, match):
 
     # Kernel ABI doesn't describe such file or symbol
     if not target:
+        if warning:
+            kernel_abi.log.warning("%s not found", fname)
         return nodes.Text(match.group(0))
 
     pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'ref',
@@ -317,6 +319,13 @@ def markup_abi_ref(docname, app, match):
     else:
         return nodes.Text(match.group(0))
 
+#
+# Variant of markup_abi_ref() that warns whan a reference is not found
+#
+def markup_abi_file_ref(docname, app, match):
+    return markup_abi_ref(docname, app, match, warning=True)
+
+
 def get_c_namespace(app, docname):
     source = app.env.doc2path(docname)
     with open(source) as f:
diff --git a/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst b/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst
index 34d6a0a1f4d3..70b5966aaff8 100644
--- a/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst
+++ b/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst
@@ -6,7 +6,7 @@
 Remote Controller's sysfs nodes
 *******************************
 
-As defined at ``Documentation/ABI/testing/sysfs-class-rc``, those are
+As defined at Documentation/ABI/testing/sysfs-class-rc, those are
 the sysfs nodes that control the Remote Controllers:
 
 
-- 
2.48.1

Re: [PATCH 0/9] Extend automarkup support for ABI symbols

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 851 bytes --]

On Tue, Feb 11, 2025 at 07:22:54AM +0100, Mauro Carvalho Chehab wrote:
> Now that ABI creates a python dictionary, use automarkup to create cross
> references for ABI symbols as well. 

I get three new warnings:

WARNING: /sys/devices/system/cpu/cpuX/topology/physical_package_id is defined 2 times: /home/bagas/repo/linux-kernel/Documentation/ABI/stable/sysfs-devices-system-cpu:27; /home/bagas/repo/linux-kernel/Documentation/ABI/testing/sysfs-devices-system-cpu:70
WARNING: /sys/devices/system/cpu/cpuX/topology/ppin is defined 2 times: /home/bagas/repo/linux-kernel/Documentation/ABI/stable/sysfs-devices-system-cpu:89; /home/bagas/repo/linux-kernel/Documentation/ABI/testing/sysfs-devices-system-cpu:70
WARNING: Documentation/ABI/testing/sysfs-class-cxl not found

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 0/9] Extend automarkup support for ABI symbols

[Mauro Carvalho Chehab]

Em Wed, 12 Feb 2025 18:25:15 +0700
Bagas Sanjaya <bagasdotme@gmail.com> escreveu:

> On Tue, Feb 11, 2025 at 07:22:54AM +0100, Mauro Carvalho Chehab wrote:
> > Now that ABI creates a python dictionary, use automarkup to create cross
> > references for ABI symbols as well.   
> 
> I get three new warnings:
> 
> WARNING: /sys/devices/system/cpu/cpuX/topology/physical_package_id is defined 2 times: /home/bagas/repo/linux-kernel/Documentation/ABI/stable/sysfs-devices-system-cpu:27; /home/bagas/repo/linux-kernel/Documentation/ABI/testing/sysfs-devices-system-cpu:70
> WARNING: /sys/devices/system/cpu/cpuX/topology/ppin is defined 2 times: /home/bagas/repo/linux-kernel/Documentation/ABI/stable/sysfs-devices-system-cpu:89; /home/bagas/repo/linux-kernel/Documentation/ABI/testing/sysfs-devices-system-cpu:70

Those two are new reports that get_abi.py detects after the recent changes.
In the past, symbol duplication were detected only within the same group
(testing, stable, ...). The new version can detect symbols that are
duplicated on different parts of the ABI. In this specific case, the same
symbols exist on both stable and testing.

There is a fix for them already at:

https://lore.kernel.org/linux-doc/673e9543783349b0fcf625018e38e4e93fe98f52.1738020236.git.mchehab+huawei@kernel.org/

> WARNING: Documentation/ABI/testing/sysfs-class-cxl not found

I need to double-check verify this one, as it didn't appear on
my tests. Are you getting it against docs-next or linux-next?

Thanks,
Mauro

Re: [PATCH 0/9] Extend automarkup support for ABI symbols

[Andrew Donnellan]

On Wed, 2025-02-12 at 13:58 +0100, Mauro Carvalho Chehab wrote:
> > WARNING: Documentation/ABI/testing/sysfs-class-cxl not found
> 
> I need to double-check verify this one, as it didn't appear on
> my tests. Are you getting it against docs-next or linux-next?
> 

This is moved to obsolete/ by 5731d41af924b which was merged in rc1,
and will be moved again to removed/ by [0].

Andrew

[0]
https://patchwork.ozlabs.org/project/linuxppc-dev/patch/20250203072801.365551-3-ajd@linux.ibm.com/

-- 
Andrew Donnellan    OzLabs, ADL Canberra
ajd@linux.ibm.com   IBM Australia Limited

Re: [PATCH 0/9] Extend automarkup support for ABI symbols

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

>> WARNING: Documentation/ABI/testing/sysfs-class-cxl not found
>
> I need to double-check verify this one, as it didn't appear on
> my tests. Are you getting it against docs-next or linux-next?

I get this one too, FWIW.

I've gone ahead and applied the series, but this would be nice to get
cleaned up.

Thanks,

jon