scripts: sphinx-pre-install: add missing gentoo pdf dependencies
There are two packages that are required to build PDF at gentoo:
dev-texlive/texlive-latexextra
media-fonts/lm
Place latex_dependencies on a list to make it easier to maintain
and add the missing ones.
With that, most PDF documents now build on Gentoo:
Gentoo Base System release 2.17:
--------------------------------
PASSED: OS detection: Gentoo Base System release 2.17
SKIPPED (Sphinx Sphinx 8.2.3): System packages
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx on venv
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx package
PASSED: Clean documentation: Build time: 0:00, return code: 0
PASSED: Build HTML documentation: Build time: 5:28, return code: 0
PARTIAL: Build PDF documentation: Test failed (Build time: 9:19, return code: 2)
scripts: sphinx-pre-install: fix PDF build issues on Ubuntu
PDF output with current Debian-based distros require other
packages for it to work. The main one is pzdr.tfm. Without
that, \sphinxhyphen{} won't work, affecting multiple docs.
For CJK, tex-gyre is required.
Add the missing packages to the list.
After the change, all PDF files build on latest Ubuntu:
Ubuntu 25.04:
-------------
PASSED: OS detection: Ubuntu 25.04
SKIPPED (Sphinx Sphinx 8.1.3): System packages
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx on venv
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx package
PASSED: Clean documentation: Build time: 0:00, return code: 0
PASSED: Build HTML documentation: Build time: 3:28, return code: 0
PASSED: Build PDF documentation: Build time: 11:08, return code: 0
Makes it more adehent with modern Sphinx LaTeX build setup as
defined at:
https://www.sphinx-doc.org/en/master/latex.html
There, it suggests:
1) to add: 'printindex'
“printindex” call, the last thing in the file. Override if you want to generate
the index differently, append some content after the index, or change the font.
As LaTeX uses two-column mode for the index it is often advisable to set this
key to r'\footnotesize\raggedright\printindex'.
This indeed solved a corner case on a distro where the index was not properly
generated.
2) to add at the main example:
\PassOptionsToPackage{svgnames}{xcolor}
3) I got a corner case on one of the distros was using xindy to produce
indexes. This ended causing the build logic to incorretly try to use
T1 fontenc, which is not UTF-8 compatible.
While PDF docs work fine on RPM-based distros, it causes conflicts
on Debian & friends.
There are multiple root causes here:
- the latex_elements still resambles the one from Sphinx 1.x
times, where font configurations were stored under
"preamble". It doesn't follow the current recommended way from
Sphinx documentation:
https://www.sphinx-doc.org/en/master/latex.html
- instead of setting the main font, from where other fonts are
derivated, it sets romanfont;
- "fontenc" is not set. This allows the *.tex output file to
contain an UTF-8 incompatible fontset:
\usepackage[T1]{fontenc}
Address such issues to help preventing incompatible usage of
both T1 font and UTF-8 ones that comes from DejaVu font
family.
On some distros, this even generate a LaTeX font warning about
corrupted NFSS tables like this (I got it when running it in
interactive mode):
Package: fontenc 2021/04/29 v2.0v Standard LaTeX package
LaTeX Font Info: Trying to load font information for T1+lmr on input line 11
6.
LaTeX Font Info: No file T1lmr.fd. on input line 116.
LaTeX Font Warning: Font shape `T1/lmr/m/n' undefined
(Font) using `T1/lmr/m/n' instead on input line 116.
docs: conf.py: use dedent and r-strings for LaTeX macros
Instead of adding extra weird indentation at the tex
file, use dedent(). While here, also use r-strings, to make
easier to make its content identical to the .tex output.
While here, also merge "preamble" that was added on two
separate parts of the code (in the past, there were some
version-specific checks).
When SPHINXDIRS is used, the current logic produces a wrong
list of files, as it will not pick the SPHINXDIRS directory,
picking instead their children.
Add a rule to detect it and create the PDF doc with the right
name.
The original logic assumed that app.srcdir is identical to the
current working dir. This is the case for a normal build, but,
when SPHINXDIRS="some dir" is used, this is not the case anymore.
Adjust the logic to fill the LaTeX documents considering
app.srcdir, in a way that it will work properly on all cases.
The documents explain the design concepts behind PREEMPT_RT and highlight key
differences necessary to achieve it.
It also include a list of requirements that must be fulfilled to support
PREEMPT_RT on a given architecture.
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"
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.
David Sterba [Wed, 13 Aug 2025 10:00:52 +0000 (12:00 +0200)]
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.
Jonathan Corbet [Thu, 14 Aug 2025 15:40:33 +0000 (09:40 -0600)]
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.
Jonathan Corbet [Thu, 14 Aug 2025 15:40:31 +0000 (09:40 -0600)]
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.
Jonathan Corbet [Thu, 14 Aug 2025 15:40:29 +0000 (09:40 -0600)]
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.
Jonathan Corbet [Wed, 13 Aug 2025 16:19:50 +0000 (10:19 -0600)]
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
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.
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.
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.
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.
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.
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:
!!! 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.
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.
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.
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.
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:
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
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.
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.
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.
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.
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.
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>
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>
projects / thirdparty / kernel / stable.git / log
