[PATCH 0/4] Raise the bar with regards to Python and Sphinx requirements

[PATCH 0/4] Raise the bar with regards to Python and Sphinx requirements

[Mauro Carvalho Chehab]

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.

Mauro Carvalho Chehab (4):
  docs: changes: update Sphinx minimal version to 3.4.3
  docs: changes: update Python minimal version
  docs: extensions: don't use utf-8 syntax for descriptions
  scripts/kernel-doc: drop Sphinx version check

 Documentation/conf.py                       |   2 +-
 Documentation/process/changes.rst           |   4 +-
 Documentation/sphinx/cdomain.py             |   7 +-
 Documentation/sphinx/kernel_abi.py          |   6 +-
 Documentation/sphinx/kernel_feat.py         |   4 +-
 Documentation/sphinx/kernel_include.py      |   4 +-
 Documentation/sphinx/kerneldoc.py           |   5 -
 Documentation/sphinx/kfigure.py             |  10 +-
 Documentation/sphinx/load_config.py         |   2 +-
 Documentation/sphinx/maintainers_include.py |   4 +-
 Documentation/sphinx/rstFlatTable.py        |  10 +-
 scripts/kernel-doc                          | 129 +++-----------------
 12 files changed, 41 insertions(+), 146 deletions(-)

-- 
2.48.1

[PATCH 1/4] docs: changes: update Sphinx minimal version to 3.4.3

[Mauro Carvalho Chehab]

Doing that allows us to get rid of all backward-compatible code.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py             | 2 +-
 Documentation/process/changes.rst | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 0c2205d536b3..3dad1f90b098 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -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
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index a0beca805362..66015c768cfc 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -58,7 +58,7 @@ 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
-- 
2.48.1

[PATCH 2/4] docs: changes: update Python minimal version

[Mauro Carvalho Chehab]

The current minimal version doesn't match what we have currently
at the Kernel:

	$ vermin -v  $(git ls-files *.py)
	...
	Minimum required versions: 3.10
	Incompatible versions:     2

Those are the Python scripts requiring versions higher than current minimal (3.5):

        !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/power/cpupower/bindings/python/test_raw_pylibcpupower.py
        !2, 3.9      tools/testing/selftests/net/rds/test.py
        !2, 3.9      tools/net/ynl/ethtool.py
        !2, 3.9      tools/net/ynl/cli.py
        !2, 3.9      scripts/checktransupdate.py
        !2, 3.8      tools/testing/selftests/tc-testing/plugin-lib/nsPlugin.py
        !2, 3.8      tools/testing/selftests/hid/tests/base.py
        !2, 3.7      tools/testing/selftests/turbostat/smi_aperf_mperf.py
        !2, 3.7      tools/testing/selftests/turbostat/defcolumns.py
        !2, 3.7      tools/testing/selftests/turbostat/added_perf_counters.py
        !2, 3.7      tools/testing/selftests/hid/tests/conftest.py
        !2, 3.7      tools/testing/kunit/qemu_config.py
        !2, 3.7      tools/testing/kunit/kunit_tool_test.py
        !2, 3.7      tools/testing/kunit/kunit.py
        !2, 3.7      tools/testing/kunit/kunit_parser.py
        !2, 3.7      tools/testing/kunit/kunit_kernel.py
        !2, 3.7      tools/testing/kunit/kunit_json.py
        !2, 3.7      tools/testing/kunit/kunit_config.py
        !2, 3.7      tools/perf/scripts/python/gecko.py
        !2, 3.7      scripts/rust_is_available_test.py
        !2, 3.7      scripts/bpf_doc.py
        !2, 3.6      tools/writeback/wb_monitor.py
        !2, 3.6      tools/workqueue/wq_monitor.py
        !2, 3.6      tools/workqueue/wq_dump.py
        !2, 3.6      tools/usb/p9_fwd.py
        !2, 3.6      tools/tracing/rtla/sample/timerlat_load.py
        !2, 3.6      tools/testing/selftests/net/openvswitch/ovs-dpctl.py
        !2, 3.6      tools/testing/selftests/net/nl_netdev.py
        !2, 3.6      tools/testing/selftests/net/lib/py/ynl.py
        !2, 3.6      tools/testing/selftests/net/lib/py/utils.py
        !2, 3.6      tools/testing/selftests/net/lib/py/nsim.py
        !2, 3.6      tools/testing/selftests/net/lib/py/netns.py
        !2, 3.6      tools/testing/selftests/net/lib/py/ksft.py
        !2, 3.6      tools/testing/selftests/kselftest/ksft.py
        !2, 3.6      tools/testing/selftests/hid/tests/test_tablet.py
        !2, 3.6      tools/testing/selftests/hid/tests/test_sony.py
        !2, 3.6      tools/testing/selftests/hid/tests/test_multitouch.py
        !2, 3.6      tools/testing/selftests/hid/tests/test_mouse.py
        !2, 3.6      tools/testing/selftests/hid/tests/base_gamepad.py
        !2, 3.6      tools/testing/selftests/hid/tests/base_device.py
        !2, 3.6      tools/testing/selftests/drivers/net/stats.py
        !2, 3.6      tools/testing/selftests/drivers/net/shaper.py
        !2, 3.6      tools/testing/selftests/drivers/net/queues.py
        !2, 3.6      tools/testing/selftests/drivers/net/ping.py
        !2, 3.6      tools/testing/selftests/drivers/net/lib/py/remote_ssh.py
        !2, 3.6      tools/testing/selftests/drivers/net/lib/py/load.py
        !2, 3.6      tools/testing/selftests/drivers/net/lib/py/__init__.py
        !2, 3.6      tools/testing/selftests/drivers/net/lib/py/env.py
        !2, 3.6      tools/testing/selftests/drivers/net/hw/rss_ctx.py
        !2, 3.6      tools/testing/selftests/drivers/net/hw/pp_alloc_fail.py
        !2, 3.6      tools/testing/selftests/drivers/net/hw/nic_performance.py
        !2, 3.6      tools/testing/selftests/drivers/net/hw/nic_link_layer.py
        !2, 3.6      tools/testing/selftests/drivers/net/hw/lib/py/linkconfig.py
        !2, 3.6      tools/testing/selftests/drivers/net/hw/lib/py/__init__.py
        !2, 3.6      tools/testing/selftests/drivers/net/hw/devmem.py
        !2, 3.6      tools/testing/selftests/drivers/net/hw/devlink_port_split.py
        !2, 3.6      tools/testing/selftests/drivers/net/hw/csum.py
        !2, 3.6      tools/testing/selftests/devices/probe/test_discoverable_devices.py
        !2, 3.6      tools/testing/selftests/bpf/test_bpftool_synctypes.py
        !2, 3.6      tools/testing/selftests/bpf/generate_udp_fragments.py
        !2, 3.6      tools/testing/kunit/run_checks.py
        !2, 3.6      tools/testing/kunit/kunit_printer.py
        !2, 3.6      tools/sched_ext/scx_show_state.py
        !2, 3.6      tools/perf/tests/shell/lib/perf_metric_validation.py
        !2, 3.6      tools/perf/tests/shell/lib/perf_json_output_lint.py
        !2, 3.6      tools/perf/scripts/python/parallel-perf.py
        !2, 3.6      tools/perf/scripts/python/flamegraph.py
        !2, 3.6      tools/perf/scripts/python/arm-cs-trace-disasm.py
        !2, 3.6      tools/perf/pmu-events/models.py
        !2, 3.6      tools/perf/pmu-events/metric_test.py
        !2, 3.6      tools/perf/pmu-events/metric.py
        !2, 3.6      tools/perf/pmu-events/jevents.py
        !2, 3.6      tools/net/ynl/ynl-gen-rst.py
        !2, 3.6      tools/net/ynl/ynl-gen-c.py
        !2, 3.6      tools/net/ynl/lib/ynl.py
        !2, 3.6      tools/net/ynl/lib/nlspec.py
        !2, 3.6      tools/crypto/tcrypt/tcrypt_speed_compare.py
        !2, 3.6      tools/cgroup/iocost_monitor.py
        !2, 3.6      tools/cgroup/iocost_coef_gen.py
        !2, 3.6      scripts/make_fit.py
        !2, 3.6      scripts/macro_checker.py
        !2, 3.6      scripts/get_abi.py
        !2, 3.6      scripts/generate_rust_analyzer.py
        !2, 3.6      scripts/gdb/linux/timerlist.py
        !2, 3.6      scripts/gdb/linux/pgtable.py
        !2, 3.6      scripts/clang-tools/run-clang-tools.py
        !2, 3.6      Documentation/sphinx/automarkup.py

Even if we exclude tools/net/sunrpc/xdrgen/, the minimal version is
Python 3.9.

Update process/changes to reflect the current minimal version required to
run Python scripts outside tools.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/process/changes.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index 66015c768cfc..d564362773b5 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -62,7 +62,7 @@ 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
 ====================== ===============  ========================================
 
-- 
2.48.1

[PATCH 3/4] docs: extensions: don't use utf-8 syntax for descriptions

[Mauro Carvalho Chehab]

None of the descriptions at the Sphinx extensions are using
non-ascii characters, so no need to place them under u"""
notation.

Also, according with:
	https://docs.python.org/3/deprecations/pending-removal-in-3.16.html

the 'u' format code is scheduled to be removed in Python 3.16.

So, let's just use """.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/cdomain.py             |  4 ++--
 Documentation/sphinx/kernel_abi.py          |  6 +++---
 Documentation/sphinx/kernel_feat.py         |  4 ++--
 Documentation/sphinx/kernel_include.py      |  4 ++--
 Documentation/sphinx/kfigure.py             | 10 +++++-----
 Documentation/sphinx/load_config.py         |  2 +-
 Documentation/sphinx/maintainers_include.py |  4 ++--
 Documentation/sphinx/rstFlatTable.py        | 10 +++++-----
 8 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index e6959af25402..6596fd00663f 100644
--- a/Documentation/sphinx/cdomain.py
+++ b/Documentation/sphinx/cdomain.py
@@ -1,6 +1,6 @@
 # -*- coding: utf-8; mode: python -*-
 # pylint: disable=W0141,C0113,C0103,C0325
-u"""
+"""
     cdomain
     ~~~~~~~
 
@@ -145,7 +145,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
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index e017b0299953..db6f0380de94 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -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
diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py
index 03ace5f01b5c..e3a51867f27b 100644
--- a/Documentation/sphinx/kernel_feat.py
+++ b/Documentation/sphinx/kernel_feat.py
@@ -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
diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py
index 638762442336..8db176045bc5 100755
--- a/Documentation/sphinx/kernel_include.py
+++ b/Documentation/sphinx/kernel_include.py
@@ -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
diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py
index 383f9a695b08..f1a7f13c9c60 100644
--- a/Documentation/sphinx/kfigure.py
+++ b/Documentation/sphinx/kfigure.py
@@ -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
diff --git a/Documentation/sphinx/load_config.py b/Documentation/sphinx/load_config.py
index 8b416bfd75ac..ec50e1ee5223 100644
--- a/Documentation/sphinx/load_config.py
+++ b/Documentation/sphinx/load_config.py
@@ -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
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index dcad0fff4723..d31cff867436 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -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):
diff --git a/Documentation/sphinx/rstFlatTable.py b/Documentation/sphinx/rstFlatTable.py
index 16bea0632555..180fbb50c337 100755
--- a/Documentation/sphinx/rstFlatTable.py
+++ b/Documentation/sphinx/rstFlatTable.py
@@ -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`.
 
-- 
2.48.1

[PATCH 4/4] scripts/kernel-doc: drop Sphinx version check

[Mauro Carvalho Chehab]

As the current minimal supported Sphinx version is 3.4.3, drop
support for older versions.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/cdomain.py   |   3 -
 Documentation/sphinx/kerneldoc.py |   5 --
 scripts/kernel-doc                | 129 ++++--------------------------
 3 files changed, 16 insertions(+), 121 deletions(-)

diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index 6596fd00663f..e8ea80d4324c 100644
--- a/Documentation/sphinx/cdomain.py
+++ b/Documentation/sphinx/cdomain.py
@@ -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
 
diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index be5b8fbf373f..39ddae6ae7dd 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -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 = []
 
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e57c5e989a0a..9b1e28426c0e 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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'});
@@ -2387,11 +2306,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
@@ -2471,17 +2385,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
-- 
2.48.1

Re: [PATCH 0/4] Raise the bar with regards to Python and Sphinx requirements

[Kees Cook]

On Tue, Feb 11, 2025 at 07:19:00AM +0100, Mauro Carvalho Chehab wrote:
> 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 those are positively ancient versions, too! 8.1.3 is current...)

> 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

I just did a quick sanity check against Ubuntu releases, and it all
looks fine: Ubuntu 20.04 had sphinx 1.8.5, so it already can't build the
docs. Ubuntu 22.04 has sphinx 4.3.2, so all good. Ubuntu 22.04 also has
Python 3.10, so also okay.

Reviewed-by: Kees Cook <kees@kernel.org>

-- 
Kees Cook

Re: [PATCH 0/4] Raise the bar with regards to Python and Sphinx requirements

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

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

OK, I've gone ahead and applied this series - let's see who screams...

Thanks,

jon