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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20250627084814.7f4a43d4@foz.lan>
Date: Fri, 27 Jun 2025 08:48:14 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Akira Yokosawa <akiyks@...il.com>
Cc: Linux Doc Mailing List <linux-doc@...r.kernel.org>, Jonathan Corbet
 <corbet@....net>, Breno Leitao <leitao@...ian.org>, "David S. Miller"
 <davem@...emloft.net>, Donald Hunter <donald.hunter@...il.com>, Eric
 Dumazet <edumazet@...gle.com>, Ignacio Encinas Rubio
 <ignacio@...cinas.com>, Jan Stancek <jstancek@...hat.com>, Marco Elver
 <elver@...gle.com>, Paolo Abeni <pabeni@...hat.com>, Randy Dunlap
 <rdunlap@...radead.org>, Ruben Wauters <rubenru09@....com>, Shuah Khan
 <skhan@...uxfoundation.org>, joel@...lfernandes.org,
 linux-kernel-mentees@...ts.linux.dev, linux-kernel@...r.kernel.org,
 lkmm@...ts.linux.dev, netdev@...r.kernel.org, peterz@...radead.org,
 stern@...land.harvard.edu
Subject: Re: [PATCH v8 13/13] docs: parser_yaml.py: fix backward
 compatibility with old docutils

Hi Akira,

Em Fri, 27 Jun 2025 08:59:16 +0900
Akira Yokosawa <akiyks@...il.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@...il.com>
> > Closes: https://lore.kernel.org/linux-doc/598b2cb7-2fd7-4388-96ba-2ddf0ab55d2a@gmail.com/
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>  
> Tested-by: Akira Yokosawa <akiyks@...il.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