1. Patchew
  2. linux
  3. [PATCH v8 00/13] Don't generate netlink .rst files inside $(srctree)
  4. View patch

[PATCH v8 13/13] docs: parser_yaml.py: fix backward compatibility with old docutils

Mauro Carvalho Chehab posted 13 patches 3 months, 2 weeks ago
There is a newer version of this series
[PATCH v8 13/13] docs: parser_yaml.py: fix backward compatibility with old docutils
Posted by Mauro Carvalho Chehab 3 months, 2 weeks ago 
As reported by Akira, older docutils versions are not compatible
with the way some Sphinx versions send tab_width. Add a code to
address it.

Closes: https://lore.kernel.org/linux-doc/598b2cb7-2fd7-4388-96ba-2ddf0ab55d2a@gmail.com/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/parser_yaml.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/sphinx/parser_yaml.py b/Documentation/sphinx/parser_yaml.py
index 8288e2ff7c7c..1602b31f448e 100755
--- a/Documentation/sphinx/parser_yaml.py
+++ b/Documentation/sphinx/parser_yaml.py
@@ -77,6 +77,10 @@ class YamlParser(Parser):
 
                 result.append(line, document.current_source, lineoffset)
 
+            # Fix backward compatibility with docutils < 0.17.1
+            if "tab_width" not in vars(document.settings):
+                document.settings.tab_width = 8
+
             rst_parser = RSTParser()
             rst_parser.parse('\n'.join(result), document)
 
-- 
2.49.0
Re: [PATCH v8 13/13] docs: parser_yaml.py: fix backward compatibility with old docutils
Posted by Akira Yokosawa 3 months, 1 week ago 
Hi Mauro,

On Thu, 26 Jun 2025 10:13:09 +0200, Mauro Carvalho Chehab wrote:
> As reported by Akira, older docutils versions are not compatible
> with the way some Sphinx versions send tab_width. Add a code to
> address it.
> 

Tested OK against debian:11's and almalinux:9's Sphinx 3.4.3, both of
which have docutils 0.16 bundled.

opensuse/leap:15.6's Sphinx 4.2.0 has docutils 0.16 with it, but it is
python 3.6 base and it does't work with the ynl integration.
As opensuse/leap:15.6 provides Sphinx 7.2.6 (on top of python 3.11) as
an alternative, obsoleting it should be acceptable.  

Reported-by: Akira Yokosawa <akiyks@gmail.com>
> Closes: https://lore.kernel.org/linux-doc/598b2cb7-2fd7-4388-96ba-2ddf0ab55d2a@gmail.com/
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Akira Yokosawa <akiyks@gmail.com>

        Thanks, Akira

> ---
>  Documentation/sphinx/parser_yaml.py | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/Documentation/sphinx/parser_yaml.py b/Documentation/sphinx/parser_yaml.py
> index 8288e2ff7c7c..1602b31f448e 100755
> --- a/Documentation/sphinx/parser_yaml.py
> +++ b/Documentation/sphinx/parser_yaml.py
> @@ -77,6 +77,10 @@ class YamlParser(Parser):
>  
>                  result.append(line, document.current_source, lineoffset)
>  
> +            # Fix backward compatibility with docutils < 0.17.1
> +            if "tab_width" not in vars(document.settings):
> +                document.settings.tab_width = 8
> +
>              rst_parser = RSTParser()
>              rst_parser.parse('\n'.join(result), document)
>
Re: [PATCH v8 13/13] docs: parser_yaml.py: fix backward compatibility with old docutils
Posted by Mauro Carvalho Chehab 3 months, 1 week ago 
Hi Akira,

Em Fri, 27 Jun 2025 08:59:16 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> Hi Mauro,
> 
> On Thu, 26 Jun 2025 10:13:09 +0200, Mauro Carvalho Chehab wrote:
> > As reported by Akira, older docutils versions are not compatible
> > with the way some Sphinx versions send tab_width. Add a code to
> > address it.
> >   
> 
> Tested OK against debian:11's and almalinux:9's Sphinx 3.4.3, both of
> which have docutils 0.16 bundled.
> 
> opensuse/leap:15.6's Sphinx 4.2.0 has docutils 0.16 with it, but it is
> python 3.6 base and it does't work with the ynl integration.
> As opensuse/leap:15.6 provides Sphinx 7.2.6 (on top of python 3.11) as
> an alternative, obsoleting it should be acceptable.  

Thank you for the tests! At changes.rst we updated the minimum
python requirement to:

	Python (optional)      3.9.x            python3 --version

So, I guess we can keep this way. 

The 3.9 requirement reflects the needs of most scripts. Still, for doc build, 
the min requirement was to support f-string, so Python 3.6.

In this specific case, it is likely some minor incompatibility, as vermin 
tool thinks that 3.6 would be enough: 

	$ vermin --no-tips --hidden --pessimistic -v tools/net/ynl/pyynl/ynl_gen_rst.py Documentation/sphinx/parser_yaml.py tools/net/ynl/pyynl/lib/*.py
	Detecting python files..
	Analyzing 6 files using 24 processes..
	2.3, 3.0     /new_devel/v4l/docs/Documentation/sphinx/parser_yaml.py
	~2, ~3       /new_devel/v4l/docs/tools/net/ynl/pyynl/lib/__init__.py
	!2, 3.6      /new_devel/v4l/docs/tools/net/ynl/pyynl/lib/doc_generator.py
	!2, 3.6      /new_devel/v4l/docs/tools/net/ynl/pyynl/lib/nlspec.py
	!2, 3.6      /new_devel/v4l/docs/tools/net/ynl/pyynl/lib/ynl.py
	!2, 3.4      /new_devel/v4l/docs/tools/net/ynl/pyynl/ynl_gen_rst.py
	Minimum required versions: 3.6
	Incompatible versions:     2

If the change is minimal, I don't mind having it fixed.

Anyway, IMO we need to add a checker at scripts/sphinx-pre-install to
warn against too old Python versions.

> 
> Reported-by: Akira Yokosawa <akiyks@gmail.com>
> > Closes: https://lore.kernel.org/linux-doc/598b2cb7-2fd7-4388-96ba-2ddf0ab55d2a@gmail.com/
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> Tested-by: Akira Yokosawa <akiyks@gmail.com>
> 
>         Thanks, Akira
> 
> > ---
> >  Documentation/sphinx/parser_yaml.py | 4 ++++
> >  1 file changed, 4 insertions(+)
> > 
> > diff --git a/Documentation/sphinx/parser_yaml.py b/Documentation/sphinx/parser_yaml.py
> > index 8288e2ff7c7c..1602b31f448e 100755
> > --- a/Documentation/sphinx/parser_yaml.py
> > +++ b/Documentation/sphinx/parser_yaml.py
> > @@ -77,6 +77,10 @@ class YamlParser(Parser):
> >  
> >                  result.append(line, document.current_source, lineoffset)
> >  
> > +            # Fix backward compatibility with docutils < 0.17.1
> > +            if "tab_width" not in vars(document.settings):
> > +                document.settings.tab_width = 8
> > +
> >              rst_parser = RSTParser()
> >              rst_parser.parse('\n'.join(result), document)
> >    
> 



Thanks,
Mauro
Re: [PATCH v8 13/13] docs: parser_yaml.py: fix backward compatibility with old docutils
Posted by Akira Yokosawa 3 months, 1 week ago 
[Dropping most CCs, +CC: Matthew]

Hi Mauro,

On Fri, 27 Jun 2025 08:48:14 +0200, Mauro Carvalho Chehab wrote:
> Hi Akira,
> 
> Em Fri, 27 Jun 2025 08:59:16 +0900
> Akira Yokosawa <akiyks@gmail.com> escreveu:
[...]

>>
>> opensuse/leap:15.6's Sphinx 4.2.0 has docutils 0.16 with it, but it is
>> python 3.6 base and it does't work with the ynl integration.
>> As opensuse/leap:15.6 provides Sphinx 7.2.6 (on top of python 3.11) as
>> an alternative, obsoleting it should be acceptable.  
> 
> Thank you for the tests! At changes.rst we updated the minimum
> python requirement to:
> 
> 	Python (optional)      3.9.x            python3 --version
> 
> So, I guess we can keep this way. 
> 
> The 3.9 requirement reflects the needs of most scripts. Still, for doc build, 
> the min requirement was to support f-string, so Python 3.6.
> 

Sorry, I was barking up the wrong tree.

An example of messages from opensuse/leap:15.6's Sphinx looks like this:

WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno -export ./fs/pstore/blk.c' processing failed with: AttributeError("'str' object has no attribute 'removesuffix'",)

The "removesuffix" is already there in scripts/lib/kdoc/kdoc_parser.py at
current docs-next.  It was added by commit 27ad33b6b349 ("kernel-doc: Fix
symbol matching for dropped suffixes") submitted by Matthew.

But I have to ask, do we really want the compatibility with python <3.9
restored?

        Thanks, Akira
Re: [PATCH v8 13/13] docs: parser_yaml.py: fix backward compatibility with old docutils
Posted by Mauro Carvalho Chehab 3 months ago 
Em Fri, 27 Jun 2025 17:37:16 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> [Dropping most CCs, +CC: Matthew]
> 
> Hi Mauro,
> 
> On Fri, 27 Jun 2025 08:48:14 +0200, Mauro Carvalho Chehab wrote:
> > Hi Akira,
> > 
> > Em Fri, 27 Jun 2025 08:59:16 +0900
> > Akira Yokosawa <akiyks@gmail.com> escreveu:  
> [...]
> 
> >>
> >> opensuse/leap:15.6's Sphinx 4.2.0 has docutils 0.16 with it, but it is
> >> python 3.6 base and it does't work with the ynl integration.
> >> As opensuse/leap:15.6 provides Sphinx 7.2.6 (on top of python 3.11) as
> >> an alternative, obsoleting it should be acceptable.    
> > 
> > Thank you for the tests! At changes.rst we updated the minimum
> > python requirement to:
> > 
> > 	Python (optional)      3.9.x            python3 --version
> > 
> > So, I guess we can keep this way. 
> > 
> > The 3.9 requirement reflects the needs of most scripts. Still, for doc build, 
> > the min requirement was to support f-string, so Python 3.6.
> >   
> 
> Sorry, I was barking up the wrong tree.
> 
> An example of messages from opensuse/leap:15.6's Sphinx looks like this:
> 
> WARNING: kernel-doc './scripts/kernel-doc.py -rst -enable-lineno -export ./fs/pstore/blk.c' processing failed with: AttributeError("'str' object has no attribute 'removesuffix'",)
> 
> The "removesuffix" is already there in scripts/lib/kdoc/kdoc_parser.py at
> current docs-next.  It was added by commit 27ad33b6b349 ("kernel-doc: Fix
> symbol matching for dropped suffixes") submitted by Matthew.
> 
> But I have to ask, do we really want the compatibility with python <3.9
> restored?

I actually wrote a patch addressing that. Yet, looking at the results 
from the tests I did for the sphinx-pre-install script, what we have is:

  PASSED 1 - OS: AlmaLinux release 9.6 (Sage Margay), Python: 3.9.21, hostname: almalinux-test
  PASSED 1 - OS: Arch Linux, Python: 3.13.5
  PASSED 1 - OS: CentOS Stream release 9, Python: 3.9.23, hostname: centos-test
  PASSED 1 - OS: Debian GNU/Linux 12, Python: 3.11.2, hostname: debian-test
  PASSED 1 - OS: Devuan GNU/Linux 5, Python: 3.11.2, hostname: devuan-test
  PASSED 1 - OS: Fedora release 42 (Adams), Python: 3.13.5
  PASSED 1 - OS: Gentoo Base System release 2.17, Python: 3.13.3
  PASSED 1 - OS: Kali GNU/Linux 2025.2, Python: 3.13.3, hostname: kali-test
  PASSED 1 - OS: Mageia 9, Python: 3.10.11, hostname: mageia-test
  PASSED 1 - OS: Linux Mint 22, Python: 3.10.12, hostname: mint-test
  PASSED 1 - OS: openEuler release 25.03, Python: 3.11.11, hostname: openeuler-test
  PASSED 1 - OS: OpenMandriva Lx 4.3, Python: 3.9.8, hostname: openmandriva-test
  PASSED 1 - OS: openSUSE Tumbleweed, Python: 3.13.5, hostname: opensuse-test
  PASSED 1 - OS: Rocky Linux release 8.9 (Green Obsidian), Python: 3.6.8, hostname: rockylinux8-test
  PASSED 3 - Sphinx on venv: Sphinx Sphinx 7.4.7, Docutils 0.21.2, Python3.9.20
  PASSED 1 - OS: Rocky Linux release 9.6 (Blue Onyx), Python: 3.9.21, hostname: rockylinux-test
  PASSED 1 - OS: Springdale Open Enterprise Linux release 9.2 (Parma), Python: 3.9.16, hostname: springdalelinux-test
  PASSED 1 - OS: Ubuntu 24.04.2 LTS, Python: 3.12.3, hostname: ubuntu-lts-test
  PASSED 1 - OS: Ubuntu 25.04, Python: 3.13.3, hostname: ubuntu-test

This is after running the script a second time after installing
either python 311 or python39 on openSUSE and OpenMandriva. On
both, it is possible to install distro-provided packages with
Python 3.9 or 3.11.

The only exception for RHEL8-based distros. On those, the
installed version is 3.6.x, which doesn't have f-strings. So,
it won't work anyway. Yet, RHEL8 powertools/epel repositories
have enough to install python 3.9 and Sphinx via venv.

With that in mind, I don't see any reason why restoring
backward-compatibility with 3.7.

But, someone things otherwise, the patch addressing it is
enclosed.


---

[PATCH] scripts: kdoc: make it backward-compatible with Python 3.7

There was a change at kdoc that ended breaking compatibility
with Python 3.7: str.removesuffix() was introduced on version
3.9.

Restore backward compatibility.

Reported-by: Akira Yokosawa <akiyks@gmail.com>
Closes: https://lore.kernel.org/linux-doc/57be9f77-9a94-4cde-aacb-184cae111506@gmail.com/
Fixes: 27ad33b6b349 ("kernel-doc: Fix symbol matching for dropped suffixes")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index 831f061f61b8..6273141033a8 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -1214,7 +1214,9 @@ class KernelDoc:
         # Found an export, trim out any special suffixes
         #
         for suffix in suffixes:
-            symbol = symbol.removesuffix(suffix)
+            # Be backward compatible with Python < 3.9
+            if symbol.endswith(suffix):
+                symbol = symbol[:-len(suffix)]
         function_set.add(symbol)
         return True

Patchew 2.1-devel-b67e4c2

© 2016 - 2025 Red Hat, Inc.