Em Mon, 10 Feb 2025 11:30:46 -0700
Jonathan Corbet <cor...@lwn.net> escreveu:
> Mauro Carvalho Chehab <mchehab+hua...@kernel.org> writes:
>
> > Hi Jon/Greg,
> >
> > This series replace get_abi.pl with a Python version.
> >
> > I originally started it due to some issues I noticed when searching for
> > ABI symbols. While I could just go ahead and fix the already existing
> > script, I noticed that the script maintainance didn't have much care over
> > all those years, probably because it is easier to find Python programmers
> > those days.
> >
> > Also, the code is complex and was not using modules or classes and
> > were using lots of global variables.
> >
> > So, I decided to rewrite it in Python. I started with a manual conversion
> > for each function. Yet, to avoid future maintainership issues, I opted to
> > divide the main code on three classes, each on a sepaparate file.
> >
> > Just like the original RFC, I opted to keep the Sphinx kernel-abi module
> > on three different phases:
> >
> > - call get_abi.py as an exec file;
> > - import AbiParser on a minimal integration scenario;
> > - cleanup the code to avoid needing to parse line numbers from the text.
> >
> > This way, if something goes wrong, it would be easier to just revert any
> > offending patches, It also provides a better rationale about what each
> > logical change is doing.
> >
> > The initial patches on this series do some preparation work and
> > cleans some ABI symbol bugs that lack ":" delimiter.
> >
> > I opted to place on this series the Sphinx and Python version updates.
> >
> > I still have ~10 patches here with additional cleanups, from the original
> > series I sent as RFC but let's get the main changes merged first.
>
> OK, I have applied this set - it seems to work for me, though it does
> lead to some changes in the organization of
> Documentation/admin-guide/abi.html in the output.
Yes. I moved the files part to separate files, as IMHO this would
make easier for people to navigate.
> It would be nice if, eventually, we could put the README link up at the
> top rather than under "ABI file",
Moving its position is not hard: all we need to do is to change abi.rst
file. See the enclosed patch.
> or even just include its contents
> there directly.
>
> Anyway, let's see how this goes :)
>
> Thanks,
>
> jon
Thanks,
Mauro
From e1b864d1d333d94430420d1d6fc15ea7d8a99b4b Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab <mchehab+hua...@kernel.org>
Date: Mon, 10 Feb 2025 21:24:06 +0100
Subject: [PATCH] docs: ABI: move README contents to the top
The ABI documentation looks a little bit better if it starts
with the contents of the README is placed at the beginning.
Suggested-by: Jonathan Corbet <cor...@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+hua...@kernel.org>
diff --git a/Documentation/admin-guide/abi-readme-file.rst
b/Documentation/admin-guide/abi-readme-file.rst
deleted file mode 100644
index 6172e4ccbda2..000000000000
--- a/Documentation/admin-guide/abi-readme-file.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-ABI README
-==========
-
-.. kernel-abi:: README
diff --git a/Documentation/admin-guide/abi.rst
b/Documentation/admin-guide/abi.rst
index 15a2dcb1388c..2067336353ae 100644
--- a/Documentation/admin-guide/abi.rst
+++ b/Documentation/admin-guide/abi.rst
@@ -4,6 +4,11 @@
Linux ABI description
=====================
+ABI README
+==========
+
+.. kernel-abi:: README
+
ABI symbols
-----------
@@ -21,7 +26,6 @@ ABI files
.. toctree::
:maxdepth: 2
- abi-readme-file
abi-stable-files
abi-testing-files
abi-obsolete-files
