mirrors/linux
2
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2026-05-10 11:40:19 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'mauro' into docs-mw

Browse Source 
Mauro says:

This series  increases the minimal requirements for Sphinx and Python, and
drop some backward-compatible code from Sphinx extension.

Looking at Sphinx release dates:

	Release 2.4.0 (released Feb 09, 2020)
	Release 2.4.4 (released Mar 05, 2020) (current minimal requirement)
	Release 3.4.0 (released Dec 20, 2020)
	Release 3.4.3 (released Jan 08, 2021)

	(https://www.sphinx-doc.org/en/master/changes/index.html)

And Python release dates, we have:

	Python	Release date
	3.5	2015-09-13    (current minimal requirement)
	3.6	2016-12-23
	3.7 	2018-06-27
	3.8 	2019-10-14
	3.9 	2020-10-05
	3.10	2021-10-04

	(according with https://en.wikipedia.org/w/index.php?title=History_of_Python)

The new minimal requirements are now compatible with the toolset available on Jan, 2021,
e.g.:
	- Sphinx 3.4.3;
	- Python 3.9

The new Sphinx minimal requirement allows dropping all backward-compatible code
we have at kernel-doc and at Sphinx extensions.

The new Python minimal requirement also matches the current required level for
almost  all scripts (*).

Those matches a 4-years old toolchain, which sounds a reasonable period
of time, as Python/Sphinx aren't required for the Kernel build.

(*) Except for a couple scripts inside tools that require python 3.10:

    $ vermin -v $(git ls-files '*.py')|grep 3.10
    !2, 3.10     tools/net/sunrpc/xdrgen/generators/__init__.py
    !2, 3.10     tools/net/sunrpc/xdrgen/generators/program.py
    !2, 3.10     tools/net/sunrpc/xdrgen/subcmds/source.py
    !2, 3.10     tools/net/sunrpc/xdrgen/xdr_ast.py
    !2, 3.10     tools/perf/scripts/python/mem-phys-addr.py
    !2, 3.10     tools/power/cpupower/bindings/python/test_raw_pylibcpupower.py

Such scripts aren't required for Kernel builds, so it should be OK to set minimal
python version to 3.9.
This commit is contained in:
Jonathan Corbet
2025-02-13 11:37:33 -07:00
parent de61d6515b 089e06c3f1
commit 629ecd68cc
12 changed files with 41 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Documentation/conf.py
View File

@@ -47,7 +47,7 @@ from load_config import loadConfig
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '2.4.4'
needs_sphinx = '3.4.3'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

4
Documentation/process/changes.rst
View File

@@ -58,11 +58,11 @@ mcelog 0.6 mcelog --version
iptables 1.4.2 iptables -V
openssl & libcrypto 1.0.0 openssl version
bc 1.06.95 bc --version
Sphinx\ [#f1]_ 2.4.4 sphinx-build --version
Sphinx\ [#f1]_ 3.4.3 sphinx-build --version
GNU tar 1.28 tar --version
gtags (optional) 6.6.5 gtags --version
mkimage (optional) 2017.01 mkimage --version
Python (optional) 3.5.x python3 --version
Python (optional) 3.9.x python3 --version
GNU AWK (optional) 5.1.0 gawk --version
====================== =============== ========================================

7
Documentation/sphinx/cdomain.py
View File

@@ -1,6 +1,6 @@
# -*- coding: utf-8; mode: python -*-
# pylint: disable=W0141,C0113,C0103,C0325
u"""
"""
cdomain
~~~~~~~
@@ -45,9 +45,6 @@ import re
__version__ = '1.1'
# Get Sphinx version
major, minor, patch = sphinx.version_info[:3]
# Namespace to be prepended to the full name
namespace = None
@@ -145,7 +142,7 @@ class CObject(Base_CObject):
}
def handle_func_like_macro(self, sig, signode):
u"""Handles signatures of function-like macros.
"""Handles signatures of function-like macros.
If the objtype is 'function' and the signature ``sig`` is a
function-like macro, the name of the macro is returned. Otherwise

6
Documentation/sphinx/kernel_abi.py
View File

@@ -2,7 +2,7 @@
# coding=utf-8
# SPDX-License-Identifier: GPL-2.0
#
u"""
"""
kernel-abi
~~~~~~~~~~
@@ -55,7 +55,7 @@ path = os.path.join(srctree, "Documentation/ABI")
_kernel_abi = None
def get_kernel_abi():
u"""
"""
Initialize kernel_abi global var, if not initialized yet.
This is needed to avoid warnings during Sphinx module initialization.
@@ -81,7 +81,7 @@ def setup(app):
class KernelCmd(Directive):
u"""KernelABI (``kernel-abi``) directive"""
"""KernelABI (``kernel-abi``) directive"""
required_arguments = 1
optional_arguments = 3

4
Documentation/sphinx/kernel_feat.py
View File

@@ -1,7 +1,7 @@
# coding=utf-8
# SPDX-License-Identifier: GPL-2.0
#
u"""
"""
kernel-feat
~~~~~~~~~~~
@@ -56,7 +56,7 @@ def setup(app):
class KernelFeat(Directive):
u"""KernelFeat (``kernel-feat``) directive"""
"""KernelFeat (``kernel-feat``) directive"""
required_arguments = 1
optional_arguments = 2

4
Documentation/sphinx/kernel_include.py
View File

@@ -2,7 +2,7 @@
# -*- coding: utf-8; mode: python -*-
# pylint: disable=R0903, C0330, R0914, R0912, E0401
u"""
"""
kernel-include
~~~~~~~~~~~~~~
@@ -56,7 +56,7 @@ def setup(app):
class KernelInclude(Include):
# ==============================================================================
u"""KernelInclude (``kernel-include``) directive"""
"""KernelInclude (``kernel-include``) directive"""
def run(self):
env = self.state.document.settings.env

5
Documentation/sphinx/kerneldoc.py
View File

@@ -62,11 +62,6 @@ class KernelDocDirective(Directive):
env = self.state.document.settings.env
cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno']
# Pass the version string to kernel-doc, as it needs to use a different
# dialect, depending what the C domain supports for each specific
# Sphinx versions
cmd += ['-sphinx-version', sphinx.__version__]
filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
export_file_patterns = []

10
Documentation/sphinx/kfigure.py
View File

@@ -1,6 +1,6 @@
# -*- coding: utf-8; mode: python -*-
# pylint: disable=C0103, R0903, R0912, R0915
u"""
"""
scalable figure and image handling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -165,7 +165,7 @@ def setup(app):
def setupTools(app):
u"""
"""
Check available build tools and log some *verbose* messages.
This function is called once, when the builder is initiated.
@@ -445,7 +445,7 @@ class kernel_image(nodes.image):
pass
class KernelImage(images.Image):
u"""KernelImage directive
"""KernelImage directive
Earns everything from ``.. image::`` directive, except *remote URI* and
*glob* pattern. The KernelImage wraps a image node into a
@@ -481,7 +481,7 @@ class kernel_figure(nodes.figure):
"""Node for ``kernel-figure`` directive."""
class KernelFigure(Figure):
u"""KernelImage directive
"""KernelImage directive
Earns everything from ``.. figure::`` directive, except *remote URI* and
*glob* pattern. The KernelFigure wraps a figure node into a kernel_figure
@@ -557,7 +557,7 @@ class kernel_render(nodes.General, nodes.Inline, nodes.Element):
pass
class KernelRender(Figure):
u"""KernelRender directive
"""KernelRender directive
Render content by external tool. Has all the options known from the
*figure* directive, plus option ``caption``. If ``caption`` has a

2
Documentation/sphinx/load_config.py
View File

@@ -9,7 +9,7 @@ from sphinx.util.osutil import fs_encoding
def loadConfig(namespace):
# ------------------------------------------------------------------------------
u"""Load an additional configuration file into *namespace*.
"""Load an additional configuration file into *namespace*.
The name of the configuration file is taken from the environment
``SPHINX_CONF``. The external configuration file extends (or overwrites) the

4
Documentation/sphinx/maintainers_include.py
View File

@@ -3,7 +3,7 @@
# -*- coding: utf-8; mode: python -*-
# pylint: disable=R0903, C0330, R0914, R0912, E0401
u"""
"""
maintainers-include
~~~~~~~~~~~~~~~~~~~
@@ -37,7 +37,7 @@ def setup(app):
)
class MaintainersInclude(Include):
u"""MaintainersInclude (``maintainers-include``) directive"""
"""MaintainersInclude (``maintainers-include``) directive"""
required_arguments = 0
def parse_maintainers(self, path):

10
Documentation/sphinx/rstFlatTable.py
View File

@@ -2,7 +2,7 @@
# -*- coding: utf-8; mode: python -*-
# pylint: disable=C0330, R0903, R0912
u"""
"""
flat-table
~~~~~~~~~~
@@ -99,7 +99,7 @@ class colSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
class FlatTable(Table):
# ==============================================================================
u"""FlatTable (``flat-table``) directive"""
"""FlatTable (``flat-table``) directive"""
option_spec = {
'name': directives.unchanged
@@ -135,7 +135,7 @@ class FlatTable(Table):
class ListTableBuilder(object):
# ==============================================================================
u"""Builds a table from a double-stage list"""
"""Builds a table from a double-stage list"""
def __init__(self, directive):
self.directive = directive
@@ -212,7 +212,7 @@ class ListTableBuilder(object):
raise SystemMessagePropagation(error)
def parseFlatTableNode(self, node):
u"""parses the node from a :py:class:`FlatTable` directive's body"""
"""parses the node from a :py:class:`FlatTable` directive's body"""
if len(node) != 1 or not isinstance(node[0], nodes.bullet_list):
self.raiseError(
@@ -225,7 +225,7 @@ class ListTableBuilder(object):
self.roundOffTableDefinition()
def roundOffTableDefinition(self):
u"""Round off the table definition.
"""Round off the table definition.
This method rounds off the table definition in :py:member:`rows`.

129
scripts/kernel-doc
View File

@@ -26,7 +26,7 @@ kernel-doc - Print formatted kernel documentation to stdout
kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wreturn] [-Wshort-desc[ription]] [-Wcontents-before-sections]
[ -man |
-rst [-sphinx-version VERSION] [-enable-lineno] |
-rst [-enable-lineno] |
-none
]
[
@@ -130,7 +130,6 @@ if ($#ARGV == -1) {
}
my $kernelversion;
my ($sphinx_major, $sphinx_minor, $sphinx_patch);
my $dohighlight = "";
@@ -347,23 +346,6 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
$enable_lineno = 1;
} elsif ($cmd eq 'show-not-found') {
$show_not_found = 1; # A no-op but don't fail
} elsif ($cmd eq "sphinx-version") {
my $ver_string = shift @ARGV;
if ($ver_string =~ m/^(\d+)(\.\d+)?(\.\d+)?/) {
$sphinx_major = $1;
if (defined($2)) {
$sphinx_minor = substr($2,1);
} else {
$sphinx_minor = 0;
}
if (defined($3)) {
$sphinx_patch = substr($3,1)
} else {
$sphinx_patch = 0;
}
} else {
die "Sphinx version should either major.minor or major.minor.patch format\n";
}
} else {
# Unknown argument
pod2usage(
@@ -387,8 +369,6 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
# continue execution near EOF;
# The C domain dialect changed on Sphinx 3. So, we need to check the
# version in order to produce the right tags.
sub findprog($)
{
foreach(split(/:/, $ENV{PATH})) {
@@ -396,42 +376,6 @@ sub findprog($)
}
}
sub get_sphinx_version()
{
my $ver;
my $cmd = "sphinx-build";
if (!findprog($cmd)) {
my $cmd = "sphinx-build3";
if (!findprog($cmd)) {
$sphinx_major = 1;
$sphinx_minor = 2;
$sphinx_patch = 0;
printf STDERR "Warning: Sphinx version not found. Using default (Sphinx version %d.%d.%d)\n",
$sphinx_major, $sphinx_minor, $sphinx_patch;
return;
}
}
open IN, "$cmd --version 2>&1 |";
while (<IN>) {
if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
$sphinx_major = $1;
$sphinx_minor = $2;
$sphinx_patch = $3;
last;
}
# Sphinx 1.2.x uses a different format
if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
$sphinx_major = $1;
$sphinx_minor = $2;
$sphinx_patch = $3;
last;
}
}
close IN;
}
# get kernel version from env
sub get_kernel_version() {
my $version = 'unknown kernel version';
@@ -859,9 +803,10 @@ sub output_function_rst(%) {
$signature .= ")";
}
if ($sphinx_major < 3) {
if ($args{'typedef'} || $args{'functiontype'} eq "") {
print ".. c:macro:: ". $args{'function'} . "\n\n";
if ($args{'typedef'}) {
print ".. c:type:: ". $args{'function'} . "\n\n";
print_lineno($declaration_start_line);
print " **Typedef**: ";
$lineprefix = "";
@@ -869,25 +814,10 @@ sub output_function_rst(%) {
print "\n\n**Syntax**\n\n";
print " ``$signature``\n\n";
} else {
print ".. c:function:: $signature\n\n";
print "``$signature``\n\n";
}
} else {
if ($args{'typedef'} || $args{'functiontype'} eq "") {
print ".. c:macro:: ". $args{'function'} . "\n\n";
if ($args{'typedef'}) {
print_lineno($declaration_start_line);
print " **Typedef**: ";
$lineprefix = "";
output_highlight_rst($args{'purpose'});
print "\n\n**Syntax**\n\n";
print " ``$signature``\n\n";
} else {
print "``$signature``\n\n";
}
} else {
print ".. c:function:: $signature\n\n";
}
print ".. c:function:: $signature\n\n";
}
if (!$args{'typedef'}) {
@@ -955,13 +885,9 @@ sub output_enum_rst(%) {
my $count;
my $outer;
if ($sphinx_major < 3) {
my $name = "enum " . $args{'enum'};
print "\n\n.. c:type:: " . $name . "\n\n";
} else {
my $name = $args{'enum'};
print "\n\n.. c:enum:: " . $name . "\n\n";
}
my $name = $args{'enum'};
print "\n\n.. c:enum:: " . $name . "\n\n";
print_lineno($declaration_start_line);
$lineprefix = " ";
output_highlight_rst($args{'purpose'});
@@ -992,11 +918,8 @@ sub output_typedef_rst(%) {
my $oldprefix = $lineprefix;
my $name;
if ($sphinx_major < 3) {
$name = "typedef " . $args{'typedef'};
} else {
$name = $args{'typedef'};
}
$name = $args{'typedef'};
print "\n\n.. c:type:: " . $name . "\n\n";
print_lineno($declaration_start_line);
$lineprefix = " ";
@@ -1012,17 +935,13 @@ sub output_struct_rst(%) {
my ($parameter);
my $oldprefix = $lineprefix;
if ($sphinx_major < 3) {
my $name = $args{'type'} . " " . $args{'struct'};
print "\n\n.. c:type:: " . $name . "\n\n";
my $name = $args{'struct'};
if ($args{'type'} eq 'union') {
print "\n\n.. c:union:: " . $name . "\n\n";
} else {
my $name = $args{'struct'};
if ($args{'type'} eq 'union') {
print "\n\n.. c:union:: " . $name . "\n\n";
} else {
print "\n\n.. c:struct:: " . $name . "\n\n";
}
print "\n\n.. c:struct:: " . $name . "\n\n";
}
print_lineno($declaration_start_line);
$lineprefix = " ";
output_highlight_rst($args{'purpose'});
@@ -2383,11 +2302,6 @@ sub process_file($) {
close IN_FILE;
}
if ($output_mode eq "rst") {
get_sphinx_version() if (!$sphinx_major);
}
$kernelversion = get_kernel_version();
# generate a sequence of code that will splice in highlighting information
@@ -2454,17 +2368,6 @@ Do not output documentation, only warnings.
=head3 reStructuredText only
=over 8
=item -sphinx-version VERSION
Use the ReST C domain dialect compatible with a specific Sphinx Version.
If not specified, kernel-doc will auto-detect using the sphinx-build version
found on PATH.
=back
=head2 Output selection (mutually exclusive):
=over 8