[v1] Raise the bar with regards to Python and Sphinx requirements

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

Posted by Mauro Carvalho Chehab 10 months ago

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

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

Posted by Jonathan Corbet 10 months ago

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

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

Posted by Kees Cook 10 months ago

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