summaryrefslogtreecommitdiff
path: root/scripts
AgeCommit message (Collapse)Author
2025-08-13Merge branch 'pre-install' into docs-mwJonathan Corbet
Mauro says: that's the second version of the patch series which converts sphinx-pre-install to Python. The core patches are basically the same as on v1, but it has lots of fixes over the original script after testing sphinx-install on 22 distros. Please notice that I have a separate patch series addressing issues that are specific to PDF generation. Test Results Summary: ==================== PASSED - AlmaLinux release 9.6 (Sage Margay) (4 tests) PASSED - Amazon Linux release 2023 (Amazon Linux) (4 tests) PASSED - Arch Linux (4 tests) PASSED - CentOS Stream release 9 (4 tests) PASSED - Debian GNU/Linux 12 (4 tests) PASSED - Devuan GNU/Linux 5 (4 tests) PASSED - Fedora release 42 (Adams) (4 tests) PASSED - Gentoo Base System release 2.17 (4 tests) PASSED - Kali GNU/Linux 2025.2 (4 tests) PASSED - Mageia 9 (4 tests) PASSED - Linux Mint 22 (4 tests) PASSED - openEuler release 25.03 (4 tests) PARTIAL - OpenMandriva Lx 4.3 (4 tests) ensurepip package doesn't exist there. So, venv install failed. Installed via package worked PASSED - openSUSE Leap 15.6 (4 tests) PASSED - openSUSE Tumbleweed (4 tests) PASSED - Oracle Linux Server release 9.6 (4 tests) FAILED - Red Hat Enterprise Linux release 8.10 (Ootpa) (4 tests) I couldn't test properly, as it requires a repository under paywall. I suspect It should work fine PARTIAL - Rocky Linux release 8.9 (Green Obsidian) (4 tests) Install via package didn't work. Instaling via venv works. PASSED - Rocky Linux release 9.6 (Blue Onyx) (4 tests) PARTIAL - Springdale Open Enterprise Linux release 9.2 (Parma) (4 tests) Failed to install ImageMagick (affects pdf only) PASSED - Ubuntu 24.04.2 LTS (4 tests) PASSED - Ubuntu 25.04 (4 tests) In short, I expect that, for all the above, the script will properly recommend the right packages to have sphinx-build working. A more detailed list of tests that passed/failed and detected Sphinx versions can be seeing below: AlmaLinux release 9.6 (Sage Margay): ------------------------------------ PASSED: OS detection: AlmaLinux release 9.6 (Sage Margay) PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 7.4.7 PASSED: Sphinx package: Sphinx 3.4.3 Amazon Linux release 2023 (Amazon Linux): ----------------------------------------- PASSED: OS detection: Amazon Linux release 2023 (Amazon Linux) PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 7.4.7 PASSED: Sphinx package: Sphinx 3.4.3 Arch Linux: ----------- PASSED: OS detection: Arch Linux PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 8.2.3 CentOS Stream release 9: ------------------------ PASSED: OS detection: CentOS Stream release 9 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 7.4.7 PASSED: Sphinx package: Sphinx 3.4.3 Debian GNU/Linux 12: -------------------- PASSED: OS detection: Debian GNU/Linux 12 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 5.3.0 Devuan GNU/Linux 5: ------------------- PASSED: OS detection: Devuan GNU/Linux 5 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 5.3.0 Fedora release 42 (Adams): -------------------------- PASSED: OS detection: Fedora release 42 (Adams) PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 8.1.3 Gentoo Base System release 2.17: -------------------------------- PASSED: OS detection: Gentoo Base System release 2.17 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 8.2.3 Kali GNU/Linux 2025.2: ---------------------- PASSED: OS detection: Kali GNU/Linux 2025.2 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 8.1.3 Mageia 9: --------- PASSED: OS detection: Mageia 9 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 6.1.3 PASSED: Sphinx package: Sphinx 6.1.3 Linux Mint 22: -------------- PASSED: OS detection: Linux Mint 22 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.1.3 PASSED: Sphinx package: Sphinx 4.3.2 openEuler release 25.03: ------------------------ PASSED: OS detection: openEuler release 25.03 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 8.1.3 OpenMandriva Lx 4.3: -------------------- PASSED: OS detection: OpenMandriva Lx 4.3 FAILED: System packages: Error: Unable to find a match: ensurepip FAILED: Sphinx on venv: Installation failed PASSED: Sphinx package: Sphinx 4.3.2 openSUSE Leap 15.6: ------------------- PASSED: OS detection: openSUSE Leap 15.6 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 7.2.6 openSUSE Tumbleweed: -------------------- PASSED: OS detection: openSUSE Tumbleweed PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 8.2.3 Oracle Linux Server release 9.6: -------------------------------- PASSED: OS detection: Oracle Linux Server release 9.6 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 7.4.7 PASSED: Sphinx package: Sphinx 3.4.3 Red Hat Enterprise Linux release 8.10 (Ootpa): ---------------------------------------------- PASSED: OS detection: Red Hat Enterprise Linux release 8.10 (Ootpa) FAILED: System packages: Error: Unable to find a match: google-noto-sans-cjk-ttc-fonts librsvg2-tools texlive-amscls texlive-amsfonts texlive-amsmath texlive-anyfontsize texlive-capt-of texlive-cmap texlive-collection-fontsrecommended texlive-collection-latex texlive-ec texlive-eqparbox texlive-euenc texlive-fancybox texlive-fancyvrb texlive-float texlive-fncychap texlive-framed texlive-luatex85 texlive-mdwtools texlive-multirow texlive-needspace texlive-oberdiek texlive-parskip texlive-polyglossia texlive-psnfss texlive-tabulary texlive-threeparttable texlive-titlesec texlive-tools texlive-ucs texlive-upquote texlive-wrapfig texlive-xecjk texlive-xetex-bin FAILED: Sphinx on venv: No Sphinx version detected FAILED: Sphinx package: No Sphinx version detected Rocky Linux release 8.9 (Green Obsidian): ----------------------------------------- PASSED: OS detection: Rocky Linux release 8.9 (Green Obsidian) PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 7.4.7 FAILED: Sphinx package: No Sphinx version detected Rocky Linux release 9.6 (Blue Onyx): ------------------------------------ PASSED: OS detection: Rocky Linux release 9.6 (Blue Onyx) PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 7.4.7 PASSED: Sphinx package: Sphinx 3.4.3 Springdale Open Enterprise Linux release 9.2 (Parma): ----------------------------------------------------- PASSED: OS detection: Springdale Open Enterprise Linux release 9.2 (Parma) FAILED: System packages: Error: Problem: package ImageMagick-6.9.13.25-1.el9.x86_64 requires libMagickCore-6.Q16.so.7()(64bit), but none of the providers can be installed - package ImageMagick-6.9.13.25-1.el9.x86_64 requires libMagickWand-6.Q16.so.7()(64bit), but none of the providers can be installed - package ImageMagick-6.9.13.25-1.el9.x86_64 requires ImageMagick-libs(x86-64) = 6.9.13.25-1.el9, but none of the providers can be installed - conflicting requests - nothing provides libraw_r.so.23()(64bit) needed by ImageMagick-libs-6.9.13.25-1.el9.x86_64 PASSED: Sphinx on venv: Sphinx 7.4.7 PASSED: Sphinx package: Sphinx 3.4.3 Ubuntu 24.04.2 LTS: ------------------- PASSED: OS detection: Ubuntu 24.04.2 LTS PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 7.2.6 Ubuntu 25.04: ------------- PASSED: OS detection: Ubuntu 25.04 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 8.1.3 Summary ======= PASSED - AlmaLinux release 9.6 (Sage Margay) (4 tests) PASSED - Amazon Linux release 2023 (Amazon Linux) (4 tests) PASSED - Arch Linux (4 tests) PASSED - CentOS Stream release 9 (4 tests) PASSED - Debian GNU/Linux 12 (4 tests) PASSED - Devuan GNU/Linux 5 (4 tests) PASSED - Fedora release 42 (Adams) (4 tests) PASSED - Gentoo Base System release 2.17 (4 tests) PASSED - Kali GNU/Linux 2025.2 (4 tests) PASSED - Mageia 9 (4 tests) PASSED - Linux Mint 22 (4 tests) PASSED - openEuler release 25.03 (4 tests) FAILED - OpenMandriva Lx 4.3 (4 tests) PASSED - openSUSE Leap 15.6 (4 tests) PASSED - openSUSE Tumbleweed (4 tests) PASSED - Oracle Linux Server release 9.6 (4 tests) FAILED - Red Hat Enterprise Linux release 8.10 (Ootpa) (4 tests) FAILED - Rocky Linux release 8.9 (Green Obsidian) (4 tests) PASSED - Rocky Linux release 9.6 (Blue Onyx) (4 tests) FAILED - Springdale Open Enterprise Linux release 9.2 (Parma) (4 tests) PASSED - Ubuntu 24.04.2 LTS (4 tests) PASSED - Ubuntu 25.04 (4 tests) (base) mchehab@foz /new_devel/mchehab_scripts $ ktap_reader.py /tmp/test_logs/* AlmaLinux release 9.6 (Sage Margay): ------------------------------------ PASSED: OS detection: AlmaLinux release 9.6 (Sage Margay) PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 7.4.7 PASSED: Sphinx package: Sphinx 3.4.3 Amazon Linux release 2023 (Amazon Linux): ----------------------------------------- PASSED: OS detection: Amazon Linux release 2023 (Amazon Linux) PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 7.4.7 PASSED: Sphinx package: Sphinx 3.4.3 Arch Linux: ----------- PASSED: OS detection: Arch Linux PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 8.2.3 CentOS Stream release 9: ------------------------ PASSED: OS detection: CentOS Stream release 9 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 7.4.7 PASSED: Sphinx package: Sphinx 3.4.3 Debian GNU/Linux 12: -------------------- PASSED: OS detection: Debian GNU/Linux 12 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 5.3.0 Devuan GNU/Linux 5: ------------------- PASSED: OS detection: Devuan GNU/Linux 5 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 5.3.0 Fedora release 42 (Adams): -------------------------- PASSED: OS detection: Fedora release 42 (Adams) PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 8.1.3 Gentoo Base System release 2.17: -------------------------------- PASSED: OS detection: Gentoo Base System release 2.17 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 8.2.3 Kali GNU/Linux 2025.2: ---------------------- PASSED: OS detection: Kali GNU/Linux 2025.2 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 8.1.3 Mageia 9: --------- PASSED: OS detection: Mageia 9 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 6.1.3 PASSED: Sphinx package: Sphinx 6.1.3 Linux Mint 22: -------------- PASSED: OS detection: Linux Mint 22 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.1.3 PASSED: Sphinx package: Sphinx 4.3.2 openEuler release 25.03: ------------------------ PASSED: OS detection: openEuler release 25.03 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 8.1.3 OpenMandriva Lx 4.3: -------------------- PASSED: OS detection: OpenMandriva Lx 4.3 FAILED: System packages: Error: Unable to find a match: ensurepip PARTIAL: Sphinx on venv: Installation failed PASSED: Sphinx package: Sphinx 4.3.2 openSUSE Leap 15.6: ------------------- PASSED: OS detection: openSUSE Leap 15.6 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 7.2.6 openSUSE Tumbleweed: -------------------- PASSED: OS detection: openSUSE Tumbleweed PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 8.2.3 Oracle Linux Server release 9.6: -------------------------------- PASSED: OS detection: Oracle Linux Server release 9.6 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 7.4.7 PASSED: Sphinx package: Sphinx 3.4.3 Red Hat Enterprise Linux release 8.10 (Ootpa): ---------------------------------------------- PASSED: OS detection: Red Hat Enterprise Linux release 8.10 (Ootpa) FAILED: System packages: Error: Unable to find a match: google-noto-sans-cjk-ttc-fonts librsvg2-tools texlive-amscls texlive-amsfonts texlive-amsmath texlive-anyfontsize texlive-capt-of texlive-cmap texlive-collection-fontsrecommended texlive-collection-latex texlive-ec texlive-eqparbox texlive-euenc texlive-fancybox texlive-fancyvrb texlive-float texlive-fncychap texlive-framed texlive-luatex85 texlive-mdwtools texlive-multirow texlive-needspace texlive-oberdiek texlive-parskip texlive-polyglossia texlive-psnfss texlive-tabulary texlive-threeparttable texlive-titlesec texlive-tools texlive-ucs texlive-upquote texlive-wrapfig texlive-xecjk texlive-xetex-bin PARTIAL: Sphinx on venv: No Sphinx version detected PARTIAL: Sphinx package: No Sphinx version detected Rocky Linux release 8.9 (Green Obsidian): ----------------------------------------- PASSED: OS detection: Rocky Linux release 8.9 (Green Obsidian) PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 7.4.7 PARTIAL: Sphinx package: No Sphinx version detected Rocky Linux release 9.6 (Blue Onyx): ------------------------------------ PASSED: OS detection: Rocky Linux release 9.6 (Blue Onyx) PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 7.4.7 PASSED: Sphinx package: Sphinx 3.4.3 Springdale Open Enterprise Linux release 9.2 (Parma): ----------------------------------------------------- PASSED: OS detection: Springdale Open Enterprise Linux release 9.2 (Parma) FAILED: System packages: Error: Problem: package ImageMagick-6.9.13.25-1.el9.x86_64 requires libMagickCore-6.Q16.so.7()(64bit), but none of the providers can be installed - package ImageMagick-6.9.13.25-1.el9.x86_64 requires libMagickWand-6.Q16.so.7()(64bit), but none of the providers can be installed - package ImageMagick-6.9.13.25-1.el9.x86_64 requires ImageMagick-libs(x86-64) = 6.9.13.25-1.el9, but none of the providers can be installed - conflicting requests - nothing provides libraw_r.so.23()(64bit) needed by ImageMagick-libs-6.9.13.25-1.el9.x86_64 PASSED: Sphinx on venv: Sphinx 7.4.7 PASSED: Sphinx package: Sphinx 3.4.3 Ubuntu 24.04.2 LTS: ------------------- PASSED: OS detection: Ubuntu 24.04.2 LTS PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 7.2.6 Ubuntu 25.04: ------------- PASSED: OS detection: Ubuntu 25.04 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx 8.2.3 PASSED: Sphinx package: Sphinx 8.1.3
2025-08-13scripts: sphinx-pre-install: some adjustments related to venvMauro Carvalho Chehab
While nothing was really needed for virtualenv to work on most distros, we had an issue with OpenMandriva. While checking for it, it was noticed that there was no check if python-virtualenv was installed. This didn't solve the issues we faced there: at least with the half-broken OpenMandriva Lx 4.0 docker container we used, ensurepip was not available anywhere, causing venv to fail. Add a distro-specific note about that. Note: at least at the time we did our tests, OpenMandriva Lx 4.0 docker was shipped with wrong dnf repositories. Also, there was no repos available for it anymore. So, we had to do some hacks to upgrade to 4.3 before being able to run any tests. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/e3a0e5eccd50eb506846e3e8487a2d9124ef83e2.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: add a warning for Debian-based distrosMauro Carvalho Chehab
On Some Debian-based distros, ImageMagick package has a broken policy that causes LaTeX to fail while building docs. Add a note about that. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/628d01784e8c24e3d93c69c436f12398e00165b3.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: add support for RHEL8-based distrosMauro Carvalho Chehab
On RHEL8, only installing with a venv is supported, as there's no Sphinx package using Python 3.7 or upper. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/bcdde20edab07be6bf447eac18eecdd88c7f947c.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: update mandatory system depsMauro Carvalho Chehab
To build docs, gcc is not needed. Also, Kernel can be built nowadays with clang. So, drop it. On the other hand, which is needed. Add a system dependency for it. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/4ec979e4692c9e4acd6c31424c0e2f4bf5b80e71.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install.pl: get rid of the old scriptMauro Carvalho Chehab
All features were ported to the Python version. Plus, it supports more variants and contain fixes. So, drop the old version. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/6900872e6b89b7ff304e70f5d1c23cbb3c757d28.1754992972.git.mchehab+huawei@kernel.org
2025-08-13docs: Makefile: switch to the new scripts/sphinx-pre-install.pyMauro Carvalho Chehab
Now that we have a better, improved Python script, use it when checking for documentation build dependencies. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/79508fb071512c33e807f5411bbff1904751b5d3.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: rework install command logicMauro Carvalho Chehab
Cleanup the code to remove some redundancy and to let it be clearer about the command install instructions. Ensure that special instructions will be shown only once, before the actual install command. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/a6120449d9cc14346e867d1ef8944ae28ddbf3f6.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: fix several codingstyle issuesMauro Carvalho Chehab
Address most pylint issues. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/5139b18535e1436e4b1773706224a9ec3a386697.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: add docstring documentationMauro Carvalho Chehab
This program is somewhat complex. Add some docstring documentation, explaining what each function and class is supposed to do. Most of the focus here were to describe the ancillary functions used to detect dependency needs. The main SphinxDependencyChecker still requires a lot of care, and probably need to be reorganized to clearly split the 4 types of output it produces: - Need to upgrade Python binary; - System install needs; - Virtual env install needs; - Python install needs via system packages, to run Sphinx natively. Yet, for now, I'm happy of having it a lot better documented than its Perl version. - While here, rename a parameter to have its usage better documented. No functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/0cadab2cab3f78ae6d9f378e92a45125fbc5188f.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: add documentation for the ancillary classes.Mauro Carvalho Chehab
While here, rename a parameter to have its usage better documented. No functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/7421112b14edf5c21cc4cf0f2ee320fcaf874b40.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: move get_system_release()Mauro Carvalho Chehab
The code at get_system_release() is actually a helper function, independent from the actual Sphinx verification checker. Move it to MissingCheckers class, where other checkers are present. With that, the entire distro-specific handler logic, with all its complexity is confined at SphinxDependencyChecker class. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/4b42a85bbb6575bb34a58cf66019038c4afa1d5b.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: add more generic checkers on a classMauro Carvalho Chehab
Better organize the code by moving the more generic methods to MissingCheckers. Such class contain only binary and package dependent missing checkers, but no distro-specific data or code. All distro-specific data/code remains at SphinxDependencyChecker class. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/11a252fe816bd7c85583d26ade0666eb2b481bf0.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: move ancillary checkers to a separate classMauro Carvalho Chehab
The code there are just a bunch of static functions that are used by the main class. group them altogether to better organize the code. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/e2671eb14fae7a8510f5305ac44ad8063e237a5f.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: move missing logic to a separate classMauro Carvalho Chehab
Better manage dependencies by placing them on a distro-independent class. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/f4f5bf276e07dc494f5dc83c4c2d087be7f790e6.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: better handle RHEL-based distrosMauro Carvalho Chehab
Better implement support for RHEL-based distros. While here, get rid of a Fedora 28 support which cause troubles with server distros. Also, get rid of yum, as RHEL8 already suppords dnf, and this is not the minimal version we may still support. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/4d1b27d3a381f011e150bb50176babba83af9e1a.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: convert is_optional to a classMauro Carvalho Chehab
When is_optional was added in Perl, it was a boolean. With time, it ended becoming a sort of enum, which makes the module harder to maintain. Convert it to a enum-like class and add more options to it. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/42290a24f3b1dbea9ebe19747cf5622bb2f2cf5c.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: better handle Python min versionMauro Carvalho Chehab
Don't do any recommendations about Sphinx install with too old python versions. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/013aeb848ecc3f6b69b4518cf3d335bd2353b6e1.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: adjust a warning messageMauro Carvalho Chehab
There is one extra space at the first line. Also, as now we only support Python 3.4+, update the text. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/74a17edd70364ca623a54b62bd97a344bb474988.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: move package instructions to a new funcMauro Carvalho Chehab
Currently, if Python < 3.7, package install will fail. That happens with OpenSuse Leap and RHEL-based ver 8 distros. OpenSuse allows installing Sphinx with Python 3.11, but RHEL-based distros don't. Prepare to recomend only venv on such cases. For now, just split the recomendation on a new function that will check for a paramtere to be called. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/4fb2181c960e89774309a833f80209a1a3ab10d2.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: fix OpenMandriva supportMauro Carvalho Chehab
OpenMandriva Lx 4.3 has different package names for ImageMagick and yaml. Fix them to ensure that system setup will pass. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/0b4e7aa88c96e6a5b8f2e6f381b3e21124680d33.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: improve Gentoo package deps logicMauro Carvalho Chehab
It took me a lot of time, but I guess understand now what it takes to install a package on Gentoo. Handling dependencies is a nightmare, as Gentoo refuses to emerge some packages if there's no package.use file describing them. To make it worse, compilation flags shall also be present there for some packages. If USE is not perfect, error/warning messages like those are shown: gnome-base/librsvg dev-texlive/texlive-xetex media-fonts/dejavu dev-python/pyyaml ... !!! The following binary packages have been ignored due to non matching USE: =media-gfx/graphviz-12.2.1-r1 X pdf -python_single_target_python3_13 qt6 svg =media-gfx/graphviz-12.2.1-r1 X pdf python_single_target_python3_12 -python_single_target_python3_13 qt6 svg =media-gfx/graphviz-12.2.1-r1 X pdf qt6 svg =media-gfx/graphviz-12.2.1-r1 X pdf -python_single_target_python3_10 qt6 svg =media-gfx/graphviz-12.2.1-r1 X pdf -python_single_target_python3_10 python_single_target_python3_12 -python_single_target_python3_13 qt6 svg =media-fonts/noto-cjk-20190416 X =app-text/texlive-core-2024-r1 X cjk -xetex =app-text/texlive-core-2024-r1 X -xetex =app-text/texlive-core-2024-r1 -xetex =dev-libs/zziplib-0.13.79-r1 sdl If emerge is allowed, it will simply ignore the above packages, creating an incomplete installation, which will later fail when one tries to build docs with images or build PDFs. After the fix, command line commands to produce the needed USE chain will be emitted, if they don't exist yet. sudo su -c 'echo "media-gfx/graphviz" > /etc/portage/package.use/graphviz' sudo su -c 'echo "media-gfx/imagemagick" > /etc/portage/package.use/imagemagick' sudo su -c 'echo "media-libs/harfbuzz icu" > /etc/portage/package.use/media-libs' sudo su -c 'echo "media-fonts/noto-cjk" > /etc/portage/package.use/media-fonts' sudo su -c 'echo "app-text/texlive-core xetex" > /etc/portage/package.use/texlive' sudo su -c 'echo "dev-libs/zziplib sdl" > /etc/portage/package.use/zziblib' The new logic tries to be smart enough to detect for missing files and missing arguments. Yet, as Gentoo seems to require users to manage those package.use files by hand, the logic isn't perfect: users may still need to verify for conflicts on different use files. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/365fe5e7d568da932dcffde65f48f2c1256cb773.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: remove Scientific LinuxMauro Carvalho Chehab
According with its website: https://scientificlinux.org/ Scientific Linux reached end of life in June 30, 2024. Also, it was based on RHEL 7, which is not compatible with our build system anymore. So, drop support for it. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/dde5e0c95017022840f8a522ce44759e51f52aa1.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: fix rhel recomendationsMauro Carvalho Chehab
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/393a299a850ba9d94c6a8965e78db4da2dbf7e37.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: fix Leap support for rsvg-convertMauro Carvalho Chehab
There is a test logic meant to be for Leap, renaming rsvg-convert package. Well, at least on latest Leap releases, this is wrong, causing install to fail. Drop it. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/6fcc94533d860e2f6f4f2c7d6ceb6cca70f48bb6.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: add a missing f-string markerMauro Carvalho Chehab
I forgot one f-string marker, with turned to be affecting 3 lines, because of cut-and-paste ;-) Use the proper f-string marker to print Sphinx version at the hint lines. Yet, we don't want to print as a tuple, so call ver_str() for it. Ideally, we would be placing it directly at the f-string, but Python 3.6 f-string support was pretty much limited. Only 3.12 (PEP 701) makes it similar to Perl, allowing expressions inside it. It sounds that function call itself was introduced on 3.7. As we explicitly want this one to run on 3.6, as latest Leap comes with it, we can't use function calls on f-string. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/b0ad1795446b17a00ba2dd83f366e784253668e6.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: output Python and docutils versionMauro Carvalho Chehab
Specially when debugging issues, knowing the versions is important. Add it to the script output. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/96142ec916b9064c859b200639c3595115080322.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: cleanup rhel supportMauro Carvalho Chehab
Rhel < 8.0 is not supported anymore. Drop support for it. Rhel 8 is problematic: at least on the tests I did with a docker repo, it didn't work, but it could be due to the issue that it is actually different than a real One. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/62fe8ab243ad39f4964f1f74b965e43dc8f10e23.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: only show portage hints onceMauro Carvalho Chehab
On gentoo, doesn't repeat instructions about how to enable portage. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/d4e7ef1d5e1f0412eb9f9ae4913dc64c0821e002.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: Address issues with OpenSUSE TumbleweedMauro Carvalho Chehab
On Tumbleweed, package names are named after python-313*, as it also has older python versions on it. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/fe0b5f7c18d7b32e0229c0890371e1441ffea294.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: fix support for gentooMauro Carvalho Chehab
Some gentoo packages have changes. Fix it. While here, improve emerge portage use logic. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/283987633aae7d99e0eff41e24eb6285c1b6b335.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: fix opensuse Leap hint for PyYAMLMauro Carvalho Chehab
On Leap, the name of the package is python311-PyYAML. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/0266c5e28e136c62de33d2d7f7d5e69b273e0d01.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: Address issues with OpenSUSE Leap 15.xMauro Carvalho Chehab
On openSUSE Leap 15.6, which is the current LTS version, has two Sphinx packages. The normal one requires Python 3.6, which we don't support anymore. However, it also has Python 3.11 with a newer Sphinx version (7.2.6). Suggest the newer version: Detected OS: openSUSE Leap 15.6. ERROR: at least python 3.7 is required to build the kernel docs Warning: python version is not supported. Warning: better to also install "convert". Warning: better to also install "dot". ERROR: please install "yaml", otherwise, build won't work. You should run: sudo zypper install --no-recommends ImageMagick graphviz python311-pyyaml Sphinx needs to be installed either: 1) via pip/pypi with: Currently not possible. Please upgrade Python to a newer version and run this script again 2) As a package with: sudo zypper install --no-recommends python311-Sphinx Please note that Sphinx >= 3.0 will currently produce false-positive warning when the same name is used for more than one type (functions, structs, enums,...). This is known Sphinx bug. For more details, see: https://github.com/sphinx-doc/sphinx/pull/8313 Can't build as 2 mandatory dependencies are missing Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/a1600e292b63f96f40163e350238812158ebd6c2.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: drop support for old virtualenvMauro Carvalho Chehab
Up to Python 3.2, the virtual environment were created via virtualenv binary. As we dropped support for such old version, clean up the code. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/31afe394bcfd8f7e450263c1922d2c73b91d36d8.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: drop obsolete routinesMauro Carvalho Chehab
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/afb97854f05b0852f4c6c1fcee102e9697c14cd8.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: run on a supported versionMauro Carvalho Chehab
The scripts/sphinx-pre-install is used to detect problems at the system environment and adjust it to build the Kernel documentation. If the version is too old, it won't run, though. Check if the version which started the script is valid. If not, seek for a new one that is compatible with documentation build. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/76627055a7f82f6a79296ddbd873fa5ac8f82a1d.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: Make it compatible with Python 3.6Mauro Carvalho Chehab
The minimal version requirements we have is 3.9. Yet, the script which detects it is this one. So, let's try supporting an old version here, as we may want to suggest to upgrade Python version to build the docs. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/39d6e27a047bc3cc8208ac5e11fe6ba44faff9c4.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: Convert script to PythonMauro Carvalho Chehab
Port scripts/sphinx-pre-install to Python. That allows a better maintainance of the file. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/8d236079545aff796900bde4cdaaf79411d04074.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: rename it to scripts/sphinx-pre-install.plMauro Carvalho Chehab
That helps us to later replace the scripts. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/08d9a32a5aaf3784fef016594efe505d7c5a2697.1754992972.git.mchehab+huawei@kernel.org
2025-08-13scripts: sphinx-pre-install: fix version check for FedoraMauro Carvalho Chehab
The script is now picking the wrong version. Fix it. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/9d1e5c9906534e2bae586f891770066346463146.1754992972.git.mchehab+huawei@kernel.org
2025-08-11docs: kernel-doc: avoid script crash on ancient PythonMauro Carvalho Chehab
While we do need at least 3.6 for kernel-doc to work, and at least 3.7 for it to output functions and structs with parameters at the right order, let the python binary be compatible with legacy versions. The rationale is that the Kernel build nowadays calls kernel-doc with -none on some places. Better not to bail out when older versions are found. With that, potentially this will run with python 2.7 and 3.2+, according with vermin: $ vermin --no-tips -v ./scripts/kernel-doc Detecting python files.. Analyzing using 24 processes.. 2.7, 3.2 /new_devel/v4l/docs/scripts/kernel-doc Minimum required versions: 2.7, 3.2 3.2 minimal requirement is due to argparse. The minimal version I could check was version 3.4 (using anaconda). Anaconda doesn't support 3.2 or 3.3 anymore, and 3.2 doesn't even compile (I tested compiling Python 3.2 on Fedora 42 and on Fedora 32 - no show). With 3.4, the script didn't crash and emitted the right warning: $ conda create -n py34 python=3.4 $ conda activate py34 python --version Python 3.4.5 $ python ./scripts/kernel-doc --none include/media Error: Python 3.6 or later is required by kernel-doc $ conda deactivate $ python --version Python 3.13.5 $ python ./scripts/kernel-doc --none include/media (no warnings and script ran properly) Supporting 2.7 is out of scope, as it is EOL for 5 years, and changing shebang to point to "python" instead of "python3" would have a wider impact. I did some extra checks about the differences from 3.2 and 3.4, and didn't find anything that would cause troubles: grep -rE "yield from|asyncio|pathlib|async|await|enum" scripts/kernel-doc Also, it doesn't use "@" operator. So, I'm confident that it should run (producing the exit warning) since Python 3.2. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/87d55e76b0b1391cb7a83e3e965dbddb83fa9786.1753806485.git.mchehab+huawei@kernel.org
2025-08-11Merge branch 'dump-struct' into docs-mwJonathan Corbet
In my ongoing effort to truly understand our new kernel-doc, I continue to make changes to improve the code, and to try to make the understanding task easier for the next person. These patches focus on dump_struct() in particular, which starts out at nearly 300 lines long - to much to fit into my little brain anyway. Hopefully the result is easier to manage. There are no changes in the rendered docs.
2025-08-11docs: kdoc: a few final dump_struct() touchesJonathan Corbet
Add a couple more comments so that each phase of the process is now clearly marked. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250807211639.47286-13-corbet@lwn.net
2025-08-11docs: kdoc: extract output formatting from dump_struct()Jonathan Corbet
The last thing done in dump_struct() is to format the structure for printing. That, too, is a separate activity; split it out into its own function. dump_struct() now fits in a single, full-hight editor screen. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250807211639.47286-12-corbet@lwn.net
2025-08-11docs: kdoc: further rewrite_struct_members() cleanupJonathan Corbet
Get rid of some redundant checks, and generally tighten up the code; no logical change. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250807211639.47286-11-corbet@lwn.net
2025-08-11docs: kdoc: Some rewrite_struct_members() commentingJonathan Corbet
Add comments to rewrite_struct_members() describing what it is actually doing, and reformat/comment the main struct_members regex so that it is (more) comprehensible to humans. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250807211639.47286-10-corbet@lwn.net
2025-08-11docs: kdoc: remove an extraneous strip() callJonathan Corbet
...the variable in question was already strip()ed at the top of the loop. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250807211639.47286-9-corbet@lwn.net
2025-08-11docs: kdoc: rework the rewrite_struct_members() main loopJonathan Corbet
Adopt a more Pythonic form for the main loop of this function, getting rid of the "while True:" construction and making the actual loop invariant explicit. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250807211639.47286-8-corbet@lwn.net
2025-08-11docs: kdoc: split struct-member rewriting out of dump_struct()Jonathan Corbet
The massive loop that massages struct members shares no data with the rest of dump_struct(); split it out into its own function. Code movement only, no other changes. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250807211639.47286-7-corbet@lwn.net
2025-08-11docs: kdoc: split top-level prototype parsing out of dump_struct()Jonathan Corbet
Move the initial split of the prototype into its own function in the ongoing effort to cut dump_struct() down to size. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250807211639.47286-6-corbet@lwn.net
generated by cgit v1.2.3 (git 2.0.4) at 2025-11-23 06:47:52 +0000