[RFC,0/6] Raise the bar with regards to Python and Sphinx requirements

Message

Mauro Carvalho Chehab Jan. 29, 2025, 4:09 p.m. UTC

This series comes after https://lore.kernel.org/linux-doc/[e-mail]/T/#t
It  increases the minimal requirements for Sphinx and Python.

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)

In terms of Python, we're currently at 3.5:

	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:
	- 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 matches the current required level for
all scripts but one (*). The one that doesn't match is at tools/net/sunrpc/xdrgen.

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

Mauro Carvalho Chehab (6):
  scripts/get_abi.py: make it backward-compatible with Python 3.6
  docs: extensions: don't use utf-8 syntax for descriptions
  docs: automarkup: drop legacy support
  scripts/kernel-doc: drop Sphinx version check
  docs: changes: update Sphinx minimal version to 3.4.3
  doc: changes: update Python minimal version

 Documentation/conf.py                       |   2 +-
 Documentation/process/changes.rst           |   4 +-
 Documentation/sphinx/automarkup.py          |  32 ++---
 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/get_abi.py                          |  16 ++-
 scripts/kernel-doc                          | 129 +++-----------------
 14 files changed, 58 insertions(+), 177 deletions(-)

Comments

Donald Hunter Jan. 30, 2025, 9:33 a.m. UTC | #1

Mauro Carvalho Chehab <[e-mail]> writes:

> This series comes after https://lore.kernel.org/linux-doc/[e-mail]/T/#t
> It  increases the minimal requirements for Sphinx and Python.
>
> 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)

It's worth mentioning here that my fix for the C performance regression
landed in Sphinx 7.4.0. All versions from 3.0.0 to 7.3.x are much slower
for building the kernel docs. See #12162 here:

https://www.sphinx-doc.org/en/master/changes/7.4.html#id7

Jonathan Corbet Jan. 30, 2025, 2:31 p.m. UTC | #2

Donald Hunter <[e-mail]> writes:

> Mauro Carvalho Chehab <[e-mail]> writes:
>
>> This series comes after https://lore.kernel.org/linux-doc/[e-mail]/T/#t
>> It  increases the minimal requirements for Sphinx and Python.
>>
>> 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)
>
> It's worth mentioning here that my fix for the C performance regression
> landed in Sphinx 7.4.0. All versions from 3.0.0 to 7.3.x are much slower
> for building the kernel docs. See #12162 here:
>
> https://www.sphinx-doc.org/en/master/changes/7.4.html#id7

Indeed, we have noticed the speedup - much appreciated, thank you!

jon