| Message ID | cover.1739182025.git.mchehab+huawei@kernel.org (mailing list archive) |
|---|---|
| Headers | show |
| Series | Improve ABI documentation generation | expand |
Mauro Carvalho Chehab <mchehab+huawei@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. It would be nice if, eventually, we could put the README link up at the top rather than under "ABI file", or even just include its contents there directly. Anyway, let's see how this goes :) Thanks, jon
Em Mon, 10 Feb 2025 11:30:46 -0700 Jonathan Corbet <corbet@lwn.net> escreveu: > Mauro Carvalho Chehab <mchehab+huawei@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+huawei@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 <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@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
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. Mauro Carvalho Chehab (27): docs: sphinx: remove kernellog.py file docs: sphinx/kernel_abi: adjust coding style docs: admin-guide: abi: add SPDX tags to ABI files ABI: sysfs-class-rfkill: fix kernelversion tags ABI: sysfs-bus-coresight-*: fix kernelversion tags ABI: sysfs-driver-dma-idxd: fix date tags ABI: sysfs-fs-f2fs: fix date tags ABI: sysfs-power: fix a what tag scripts/documentation-file-ref-check: don't check perl/python scripts scripts/get_abi.py: add a Python tool to generate ReST output scripts/get_abi.py: add support for symbol search docs: use get_abi.py for ABI generation scripts/lib/abi/abi_parser.py: optimize parse_abi() function scripts/lib/abi/abi_parser.py: use an interactor for ReST output docs: sphinx/kernel_abi: use AbiParser directly docs: sphinx/kernel_abi: reduce buffer usage for ABI messages docs: sphinx/kernel_abi: properly split lines scripts/get_abi.pl: Add filtering capabilities to rest output scripts/get_abi.pl: add support to parse ABI README file docs: sphinx/kernel_abi: parse ABI files only once docs: admin-guide/abi: split files from symbols docs: sphinx/automarkup: add cross-references for ABI docs: sphinx/kernel_abi: avoid warnings during Sphinx module init scripts/lib/abi/abi_parser.py: Rename title name for ABI files scripts/lib/abi/abi_parser.py: make it backward-compatible with Python 3.6 scripts/get_abi.py: add support for undefined ABIs scripts/get_abi.pl: drop now obsoleted script Documentation/ABI/removed/sysfs-class-rfkill | 2 +- Documentation/ABI/stable/sysfs-class-rfkill | 12 +- .../ABI/stable/sysfs-driver-dma-idxd | 4 +- .../testing/sysfs-bus-coresight-devices-cti | 78 +- .../testing/sysfs-bus-coresight-devices-tpdm | 52 +- Documentation/ABI/testing/sysfs-fs-f2fs | 4 +- Documentation/ABI/testing/sysfs-power | 2 +- .../admin-guide/abi-obsolete-files.rst | 7 + Documentation/admin-guide/abi-obsolete.rst | 6 +- Documentation/admin-guide/abi-readme-file.rst | 6 + .../admin-guide/abi-removed-files.rst | 7 + Documentation/admin-guide/abi-removed.rst | 6 +- .../admin-guide/abi-stable-files.rst | 7 + Documentation/admin-guide/abi-stable.rst | 6 +- .../admin-guide/abi-testing-files.rst | 7 + Documentation/admin-guide/abi-testing.rst | 6 +- Documentation/admin-guide/abi.rst | 17 + Documentation/sphinx/automarkup.py | 47 + Documentation/sphinx/kernel_abi.py | 162 ++- Documentation/sphinx/kerneldoc.py | 14 +- Documentation/sphinx/kernellog.py | 22 - Documentation/sphinx/kfigure.py | 81 +- scripts/documentation-file-ref-check | 2 +- scripts/get_abi.pl | 1103 ----------------- scripts/get_abi.py | 214 ++++ scripts/lib/abi/abi_parser.py | 628 ++++++++++ scripts/lib/abi/abi_regex.py | 234 ++++ scripts/lib/abi/helpers.py | 38 + scripts/lib/abi/system_symbols.py | 378 ++++++ 29 files changed, 1830 insertions(+), 1322 deletions(-) create mode 100644 Documentation/admin-guide/abi-obsolete-files.rst create mode 100644 Documentation/admin-guide/abi-readme-file.rst create mode 100644 Documentation/admin-guide/abi-removed-files.rst create mode 100644 Documentation/admin-guide/abi-stable-files.rst create mode 100644 Documentation/admin-guide/abi-testing-files.rst delete mode 100644 Documentation/sphinx/kernellog.py delete mode 100755 scripts/get_abi.pl create mode 100755 scripts/get_abi.py create mode 100644 scripts/lib/abi/abi_parser.py create mode 100644 scripts/lib/abi/abi_regex.py create mode 100644 scripts/lib/abi/helpers.py create mode 100644 scripts/lib/abi/system_symbols.py