Documentation: locking: Add local_lock_nested_bh() to locktypes

local_lock_nested_bh() is used within networking where applicable.
Document why it is used and how it behaves.

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250815093858.930751-3-bigeasy@linutronix.de

Documentation: seqlock: Add a SPDX license identifier

Add a SPDX identifier. The majority of the document has been written by
Ahmed S. Darwish.

Cc: Ahmed S. Darwish <darwi@linutronix.de>
Acked-by: Ahmed S. Darwish <darwi@linutronix.de>
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250815093858.930751-2-bigeasy@linutronix.de

docs: fix trailing whitespace error and remove repeated words in propagate_umount.txt

in Documentation/filesystems/propagate_umount.txt:
line 289: remove whitespace on blank line
line 315: remove duplicate "that"
line 364: remove duplicate "in"

Signed-off-by: Raphael Pinsonneault-Thibeault <rpthibeault@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250818181934.55491-2-rpthibeault@gmail.com

docs: sysctl: add a few more top-level /proc/sys entries

Add a few missing directories under /proc/sys.
Fix punctuation and doubled words.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Rik van Riel <riel@surriel.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Reviewed-by: Rik van Riel <riel@surriel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250819075456.113623-1-rdunlap@infradead.org

docs: Corrected typo in trace/events

-Changed 'Dyamically' to 'Dynamically' in trace/events.rst

under sections 7.1 and 7.3

Signed-off-by: Mehdi Ben Hadj Khelifa <mehdi.benhadjkhelifa@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250819085040.974388-1-mehdi.benhadjkhelifa@gmail.com

docs: kernel-parameters: typo fix and add missing SPDX-License tag

Fix documentation issues by removing a duplicated word and adding the
missing SPDX-License identifier.

Signed-off-by: Bartlomiej Kubik <kubik.bartlomiej@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250819113551.34356-1-kubik.bartlomiej@gmail.com

Documentation: driver-api: usb: Limit toctree depth

toctree index in USB driver api docs currently spoils the entire docs
headings due to lack of :maxdepth: option. Add the option to limit
toctree depth to 1, mirroring usb subsystem docs in
Documentation/usb/index.rst.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250820050416.25219-1-bagasdotme@gmail.com

Documentation: conf.py: remove repeated word in comment

Remove a repeated "are" from a comment in conf.py

Signed-off-by: Albin Babu Varghese <albinbabuvarghese20@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250820194714.130513-2-albinbabuvarghese20@gmail.com

docs: Remove remainders of reiserfs

Reiserfs has been removed in 6.13, there are still some mentions in the
documentation about it and the tools. Remove those that don't seem
relevant anymore but keep references to reiserfs' r5 hash used by some
code.

There's one change in a script scripts/selinux/install_policy.sh but it
does not seem to be relevant either.

Signed-off-by: David Sterba <dsterba@suse.com>
Acked-by: Paul Moore <paul@paul-moore.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250813100053.1291961-1-dsterba@suse.com

Merge branch 'bjorn' into docs-mw

A big set of typo fixes from Bjorn Helgaas

Documentation: Fix trace typos

Fix typos.

Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250813200526.290420-9-helgaas@kernel.org

Documentation: Fix power typos

Fix typos.

Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250813200526.290420-8-helgaas@kernel.org

Documentation: Fix networking typos

Fix typos.

Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250813200526.290420-7-helgaas@kernel.org

Documentation: Fix filesystems typos

Fix typos.

Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250813200526.290420-6-helgaas@kernel.org

Documentation: Fix core-api typos

Fix typos.

Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250813200526.290420-5-helgaas@kernel.org

Documentation: Fix admin-guide typos

Fix typos.

Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250813200526.290420-4-helgaas@kernel.org

Documentation: Fix RCU typos

Fix typos.

Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250813200526.290420-3-helgaas@kernel.org

Documentation: Fix PCI typos

Fix typos.

Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250813200526.290420-2-helgaas@kernel.org

Documentation: ktap: Separate first bullet list items

The first bullet list items are shown in htmldocs output as combined
with previous paragraph due to missing blank line separator. Add it.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250814012046.21235-3-bagasdotme@gmail.com

Documentation: ktap: Correct "its" spelling

Fix possessive adjective "its" spelling.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250814012046.21235-2-bagasdotme@gmail.com

docs: kdoc: remove redundant comment stripping

By the time stuff gets to create_parameter_list(), comments have long since
been stripped out, so we do not need to do it again here.

Acked-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250814154035.328769-8-corbet@lwn.net

docs: kdoc: tighten up the pointer-to-function case

Tighten up the code and remove an unneeded regex operation.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250814154035.328769-7-corbet@lwn.net

docs: kdoc: tighten up the array-of-pointers case

Simplify one gnarly regex and remove another altogether; add a comment
describing what is going on.  There will be no #-substituted commas in this
case, so don't bother trying to put them back.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250814154035.328769-6-corbet@lwn.net

docs: kdoc: add a couple more comments in create_parameter_list()

Make what the final code is doing a bit more clear to slow readers like me.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250814154035.328769-5-corbet@lwn.net

docs: kdoc: clean up the create_parameter_list() "first arg" logic

The logic for finding the name of the first in a series of variable names
is somewhat convoluted and, in the use of .extend(), actively buggy.
Document what is happening and simplify the logic.

Acked-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250814154035.328769-4-corbet@lwn.net

docs: kdoc: tidy up space removal in create_parameter_list()

Remove a redundant test and add a comment describing what the space removal
is doing.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250814154035.328769-3-corbet@lwn.net

docs: kdoc: remove dead code

create_parameter_list() tests an argument against the same regex twice, in
two different locations; remove the pointless extra tests and the
never-executed error cases that go with them.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250814154035.328769-2-corbet@lwn.net

Documentation: Fix driver-api typos

Corrected a few spelling mistakes

functionalty ==> functionality
in Documentation/driver-api/cxl/devices/device-types.rst

adjascent ==> adjacent
in Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst

succeessful ==> successful
in Documentation/driver-api/thermal/exynos_thermal_emulation.rst

Signed-off-by: Ranganath V N <vnranganath.20@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250814184304.20448-1-vnranganath.20@gmail.com

docs: remove a duplicated word from kernel-parameters.txt

Fix kernel-doc warning in kernel-parameters.txt

WARNING: Possible repeated word: 'is'

Signed-off-by: Vivek Yadav <vivekyadav1207731111@gmail.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250816082452.219009-1-vivekyadav1207731111@gmail.com

docs: Replace dead links to spectre side channel white papers

The papers are published by Intel, AMD and MIPS.

Signed-off-by: Nikola Z. Ivanov <zlatistiv@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250816190028.55573-1-zlatistiv@gmail.com

Documentation/sphinx: Fix typo in automarkup.py

"whan" -> "when"

Signed-off-by: Iris Shi <0.0@owo.li>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/8e5ddb7d-8faf-314f-b1b1-2d15d6900862@owo.li

Merge branch 'pre-install' into docs-mw

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

scripts: sphinx-pre-install: some adjustments related to venv

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

scripts: sphinx-pre-install: add a warning for Debian-based distros

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

scripts: sphinx-pre-install: add support for RHEL8-based distros

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

scripts: sphinx-pre-install: update mandatory system deps

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

scripts: sphinx-pre-install.pl: get rid of the old script

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

docs: Makefile: switch to the new scripts/sphinx-pre-install.py

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

scripts: sphinx-pre-install: rework install command logic

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

scripts: sphinx-pre-install: fix several codingstyle issues

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

scripts: sphinx-pre-install: add docstring documentation

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

scripts: sphinx-pre-install: add documentation for the ancillary classes.

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

scripts: sphinx-pre-install: move get_system_release()

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

scripts: sphinx-pre-install: add more generic checkers on a class

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

scripts: sphinx-pre-install: move ancillary checkers to a separate class

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

scripts: sphinx-pre-install: move missing logic to a separate class

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

scripts: sphinx-pre-install: better handle RHEL-based distros

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

scripts: sphinx-pre-install: convert is_optional to a class

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

scripts: sphinx-pre-install: better handle Python min version

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

scripts: sphinx-pre-install: adjust a warning message

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

scripts: sphinx-pre-install: move package instructions to a new func

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

scripts: sphinx-pre-install: fix OpenMandriva support

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

scripts: sphinx-pre-install: improve Gentoo package deps logic

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

scripts: sphinx-pre-install: remove Scientific Linux

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

scripts: sphinx-pre-install: fix rhel recomendations

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

scripts: sphinx-pre-install: fix Leap support for rsvg-convert

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

scripts: sphinx-pre-install: add a missing f-string marker

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

scripts: sphinx-pre-install: output Python and docutils version

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

scripts: sphinx-pre-install: cleanup rhel support

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

scripts: sphinx-pre-install: only show portage hints once

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

scripts: sphinx-pre-install: Address issues with OpenSUSE Tumbleweed

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

scripts: sphinx-pre-install: fix support for gentoo

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

scripts: sphinx-pre-install: fix opensuse Leap hint for PyYAML

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

scripts: sphinx-pre-install: Address issues with OpenSUSE Leap 15.x

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

scripts: sphinx-pre-install: drop support for old virtualenv

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

scripts: sphinx-pre-install: drop obsolete routines

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

scripts: sphinx-pre-install: run on a supported version

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

scripts: sphinx-pre-install: Make it compatible with Python 3.6

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

scripts: sphinx-pre-install: Convert script to Python

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

scripts: sphinx-pre-install: rename it to scripts/sphinx-pre-install.pl

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

scripts: sphinx-pre-install: fix version check for Fedora

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

docs: arm: stm32: fix typo "busses" -> "buses"

Fix the spelling of "busses" to the preferred form "buses" in STM32 ARM
architecture documentation.

Signed-off-by: Akshaykumar Gunari <akshaygunari@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250807145119.2214-1-akshaygunari@gmail.com

Documentation/rv: Fix minor typo in monitor_synthesis page

Specifically, fix spelling of "practice"

Signed-off-by: Gopi Krishna Menon <krishnagopi487@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250810111249.93181-1-krishnagopi487@gmail.com

docs: folio_queue: Fix minor typo in folio_queue page

Specifically, fix typo 'hese'-> 'these'

Signed-off-by: Gopi Krishna Menon <krishnagopi487@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250810235346.4153-1-krishnagopi487@gmail.com

MAINTAINERS: add File entry for scripts/checktransupdate.py to DOCUMENTATION

As suggested by Nathan, add a File entry for scripts/checktransupdate.py
to the DOCUMENTATION section to maintain this script.

Link: https://lore.kernel.org/all/20250811212446.GA924610@ax162/
Signed-off-by: Dongliang Mu <dzm91@hust.edu.cn>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250812050711.2515173-1-dzm91@hust.edu.cn

Merge tag 'docs/v6.17-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-docs into mauro

Mauro says:

As discussed at:
   https://lore.kernel.org/all/20250610101331.62ba466f@foz.lan/

changeset f061c9f7d058 ("Documentation: Document each netlink family")
added a logic which generates *.rst files inside $(srctree). This is bad
when O=<BUILDDIR> is used.

A recent change renamed the yaml files used by Netlink, revealing a bad
side effect: as "make cleandocs" don't clean the produced files and symbols
appear duplicated for people that don't build the kernel from scratch.

This series adds an yaml parser extension and uses an index file with glob for
*. We opted to write such extension in a way that no actual yaml conversion
code is inside it. This makes it flexible enough to handle other types of yaml
files in the future. The actual yaml conversion logic were placed at
netlink_yml_parser.py.

As requested by YNL maintainers, this version has netlink_yml_parser.py
inside tools/net/ynl/pyynl/ directory. I don't like mixing libraries with
binaries, nor to have Python libraries spread all over the Kernel. IMO,
the best is to put all of them on a common place (scripts/lib, python/lib,
lib/python, ...) but, as this can be solved later, for now let's keep it this
way.

sphinx: parser_yaml.py: fix line numbers information

As reported by Donald, this code:

rst_parser = RSTParser()
rst_parser.parse('\n'.join(result), document)

breaks line parsing. As an alternative, I tested a variant of it:

rst_parser.parse(result, document)

but still line number was not preserved. As Donald noted,
standard Parser classes don't have a direct mechanism to preserve
line numbers from ViewList().

So, instead, let's use a mechanism similar to what we do already at
kerneldoc.py: call the statemachine mechanism directly there.

I double-checked when states and statemachine were introduced:
both were back in 2002. I also tested doc build with docutils 0.16
and 0.21.2. It worked with both, so it seems to be stable enough
for our needs.

Reported-by: Donald Hunter <donald.hunter@gmail.com>
Closes: https://lore.kernel.org/linux-doc/m24ivk78ng.fsf@gmail.com/T/#u
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

docs: parser_yaml.py: fix backward compatibility with old docutils

As reported by Akira, older docutils versions are not compatible
with the way some Sphinx versions send tab_width. Add a code to
address it.

Reported-by: Akira Yokosawa <akiyks@gmail.com>
Closes: https://lore.kernel.org/linux-doc/598b2cb7-2fd7-4388-96ba-2ddf0ab55d2a@gmail.com/
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

docs: parser_yaml.py: add support for line numbers from the parser

Instead of printing line numbers from the temp converted ReST
file, get them from the original source.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

tools: netlink_yml_parser.py: add line numbers to parsed data

When something goes wrong, we want Sphinx error to point to the
right line number from the original source, not from the
processed ReST data.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

MAINTAINERS: add netlink_yml_parser.py to linux-doc

The documentation build depends on the parsing code
at ynl_gen_rst.py. Ensure that changes to it will be c/c
to linux-doc ML and maintainers by adding an entry for
it. This way, if a change there would affect the build,
or the minimal version required for Python, doc developers
may know in advance.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Breno Leitao <leitao@debian.org>
Reviewed-by: Donald Hunter <donald.hunter@gmail.com>

docs: netlink: remove obsolete .gitignore from unused directory

The previous code was generating source rst files
under Documentation/networking/netlink_spec/. With the
Sphinx YAML parser, this is now gone. So, stop ignoring
*.rst files inside netlink specs directory.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Donald Hunter <donald.hunter@gmail.com>

tools: ynl_gen_rst.py: drop support for generating index files

As we're now using an index file with a glob, there's no need
to generate index files anymore.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Donald Hunter <donald.hunter@gmail.com>

docs: uapi: netlink: update netlink specs link

With the recent parser_yaml extension, and the removal of the
auto-generated ReST source files, the location of netlink
specs changed.

Update uAPI accordingly.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Donald Hunter <donald.hunter@gmail.com>

docs: use parser_yaml extension to handle Netlink specs

Instead of manually calling ynl_gen_rst.py, use a Sphinx extension.
This way, no .rst files would be written to the Kernel source
directories.

We are using here a toctree with :glob: property. This way, there
is no need to touch the netlink/specs/index.rst file every time
a new Netlink spec is added/renamed/removed.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Donald Hunter <donald.hunter@gmail.com>

docs: sphinx: add a parser for yaml files for Netlink specs

Add a simple sphinx.Parser to handle yaml files and add the
the code to handle Netlink specs. All other yaml files are
ignored.

The code was written in a way that parsing yaml for different
subsystems and even for different parts of Netlink are easy.

All it takes to have a different parser is to add an
import line similar to:

from doc_generator import YnlDocGenerator

adding the corresponding parser somewhere at the extension:

netlink_parser = YnlDocGenerator()

And then add a logic inside parse() to handle different
doc outputs, depending on the file location, similar to:

        if "/netlink/specs/" in fname:
            msg = self.netlink_parser.parse_yaml_file(fname)

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Donald Hunter <donald.hunter@gmail.com>

tools: ynl_gen_rst.py: cleanup coding style

Cleanup some coding style issues pointed by pylint and flake8.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Breno Leitao <leitao@debian.org>
Reviewed-by: Donald Hunter <donald.hunter@gmail.com>

docs: netlink: index.rst: add a netlink index file

Instead of generating the index file, use glob to automatically
include all data from yaml.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Donald Hunter <donald.hunter@gmail.com>

tools: ynl_gen_rst.py: Split library from command line tool

As we'll be using the Netlink specs parser inside a Sphinx
extension, move the library part from the command line parser.

While here, change the code which generates an index file
to parse inputs from both .rst and .yaml extensions. With
that, the tool can easily be tested with:

tools/net/ynl/pyynl/ynl_gen_rst.py -x -o Documentation/netlink/specs/foo.rst

Without needing to first generate a temp directory with the
rst files.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Donald Hunter <donald.hunter@gmail.com>

docs: netlink: netlink-raw.rst: use :ref: instead of :doc:

Currently, rt documents are referred with:

Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`rt-link<../../networking/netlink_spec/rt-link>`
Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`tc<../../networking/netlink_spec/tc>`
Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`tc<../../networking/netlink_spec/tc>`

Having :doc: references with relative paths doesn't always work,
as it may have troubles when O= is used. Also that's hard to
maintain, and may break if we change the way rst files are
generated from yaml. Better to use instead a reference for
the netlink family.

So, replace them by Sphinx cross-reference tag that are
created by ynl_gen_rst.py.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Donald Hunter <donald.hunter@gmail.com>

docs: filesystems: sysfs: Recommend sysfs_emit() for new code only

The advantages of converting existing sysfs show() methods to sysfs_emit()
and sysfs_emit_at() do not outweigh the risk of introducing bugs. Hence
recommend sysfs_emit() and sysfs_emit_at() only for new implementations of
show() methods.

Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: James Bottomley <James.Bottomley@HansenPartnership.com>
Cc: Martin K. Petersen <martin.petersen@oracle.com>
Signed-off-by: Bart Van Assche <bvanassche@acm.org>
Reviewed-by: Martin K. Petersen <martin.petersen@oracle.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250724153449.2433395-1-bvanassche@acm.org

Documentation: Fix minor typos

Corrected a few spelling errors and improved the phrasing
changes since v1:
--corrected as per review

Signed-off-by: Ranganath V N <vnranganath.20@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250726063645.4156-1-vnranganath.20@gmail.com

docs: admin-guide: update to current minimum pipe size default

The pipe size limit used when the fs.pipe-user-pages-soft sysctl value
is reached was increased from one to two pages in commit 46c4c9d1beb7;
update the documentation to match the new reality.

Fixes: 46c4c9d1beb7 ("pipe: increase minimum default pipe size to 2 pages")
Signed-off-by: Štěpán Němec <stepnem@smrk.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250729-pipedoc-v2-1-18b8e735a9c6@smrk.net

docs: update physical memory documentation by adding N_GENERIC_INITIATOR to enum node_states

While reading physical_memory.rst, I noticed that N_GENERIC_INITIATOR has not been update
from the node_states list, even though it's already added in commit 894c26a1c274b8eafbb4b1dad67e70e51a106061.

Signed-off-by: Kim Tae Hyun <kimth0312@gmail.com>
Acked-by: Mike Rapoport (Microsoft) <rppt@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250802125801.10068-1-kimth0312@gmail.com

docs: aoe: Remove trailing whitespace

Fix `ERROR: trailing whitespace` errors from scripts/checkpatch.pl

Signed-off-by: Osama Albahrani <osalbahr@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250804152516.16493-1-osalbahr@gmail.com

Documentation/printf: Use literal fwnode_handle

When looking for fwnode_handle in the printk format documentation, it is
only found in the Chinese translation:

    $ git grep fwnode_handle -- Documentation/*printk-formats.rst
    Documentation/translations/zh_CN/core-api/printk-formats.rst:用于打印fwnode_handles的消息。默认情况下是打印完整的节点名称，包括路径。

This happens because the original documentation talks about "fwnode
handles", without mentioning the actual type name.

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Tested-by: Kunwu Chan <kunwu.chan@linux.dev>
Reviewed-by: Kunwu Chan <kunwu.chan@linux.dev>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Reviewed-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Fixes: 3bd32d6a2ee62db3 ("lib/vsprintf: Add %pfw conversion specifier for printing fwnode names")
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/07262c55e82fc4a3e3dbe7c45713b14955271e7f.1754552156.git.geert+renesas@glider.be

docs: changes: better document Python needs

Python is listed as an optional dependency, but this is not
true, as:

1) arm (multi_v7_defconfig and other defconfigs) and arm64 defconfig
   needs it due to DRM_MSM dependencies;

2) CONFIG_LTO_CLANG runs a python script at scripts/Makefile.vmlinux_o;

3) kernel-doc is called during compilation when some DRM options
   like CONFIG_DRM_I915_WERROR are enabled;

4) allyesconfig/allmodconfig will enable CONFIG_* dependencies
   that needs it;

5) besides DRM, other subsystems seem to have logic calling *.py
   scripts.

So, better document that and change the dependency from optional
to mandatory to reflect the current needs.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Rob Herring (Arm) <robh@kernel.org>
Acked-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/b03b95b8d09358e81e4f27942839191f49b0ba80.1753806485.git.mchehab+huawei@kernel.org

docs: kernel-doc: avoid script crash on ancient Python

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

Merge branch 'dump-struct' into docs-mw

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.

docs: kdoc: a few final dump_struct() touches

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