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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

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