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

Mauro Carvalho Chehab
2025-06-27T06:48:21Z

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