Re: [PATCH v6 00/15] Don't generate netlink .rst files inside $(srctree)

Em Thu, 19 Jun 2025 10:34:59 +0900
Akira Yokosawa <[email protected]> escreveu:

> On Wed, 18 Jun 2025 18:20:32 +0200, Mauro Carvalho Chehab wrote:
> > Em Thu, 19 Jun 2025 00:46:15 +0900
> > Akira Yokosawa <[email protected]> escreveu:
> >   
> >> Quick tests against Sphinx 3.4.3 using container images based on
> >> debian:bullseye and almalinux:9, both of which have 3.4.3 as their distro
> >> packages, emits a *bunch* of warnings like the following:
> >>
> >> /<srcdir>/Documentation/netlink/specs/conntrack.yaml:: WARNING: YAML parsing error: AttributeError("'Values' object has no attribute 'tab_width'")
> >> /<srcdir>/Documentation/netlink/specs/devlink.yaml:: WARNING: YAML parsing error: AttributeError("'Values' object has no attribute 'tab_width'")
> >> /<srcdir>/Documentation/netlink/specs/dpll.yaml:: WARNING: YAML parsing error: AttributeError("'Values' object has no attribute 'tab_width'")
> >> /<srcdir>/Documentation/netlink/specs/ethtool.yaml:: WARNING: YAML parsing error: AttributeError("'Values' object has no attribute 'tab_width'")
> >> /<srcdir>/Documentation/netlink/specs/fou.yaml:: WARNING: YAML parsing error: AttributeError("'Values' object has no attribute 'tab_width'")
> >> [...]
> >>
> >> I suspect there should be a minimal required minimal version of PyYAML.  
> > 
> > Likely yes. From my side, I didn't change anything related to PyYAML, 
> > except by adding a loader at the latest patch to add line numbers.
> > 
> > The above warnings don't seem related. So, probably this was already
> > an issue.
> > 
> > Funny enough, I did, on my venv:
> > 
> > 	$ pip install PyYAML==5.1
> > 	$ tools/net/ynl/pyynl/ynl_gen_rst.py -i Documentation/netlink/specs/dpll.yaml -o Documentation/output/netlink/specs/dpll.rst -v
> > 	...
> > 	$ make clean; make SPHINXDIRS="netlink/specs" htmldocs
> > 	...
> > 
> > but didn't get any issue (I have a later version installed outside
> > venv - not sure it it will do the right thing).
> > 
> > That's what I have at venv:
> > 
> > ----------------------------- ---------
> > Package                       Version
> > ----------------------------- ---------
> > alabaster                     0.7.13
> > babel                         2.17.0
> > certifi                       2025.6.15
> > charset-normalizer            3.4.2
> > docutils                      0.17.1
> > idna                          3.10
> > imagesize                     1.4.1
> > Jinja2                        2.8.1
> > MarkupSafe                    1.1.1
> > packaging                     25.0
> > pip                           25.1.1
> > Pygments                      2.19.1
> > PyYAML                        5.1
> > requests                      2.32.4
> > setuptools                    80.1.0
> > snowballstemmer               3.0.1
> > Sphinx                        3.4.3
> > sphinxcontrib-applehelp       1.0.4
> > sphinxcontrib-devhelp         1.0.2
> > sphinxcontrib-htmlhelp        2.0.1
> > sphinxcontrib-jsmath          1.0.1
> > sphinxcontrib-qthelp          1.0.3
> > sphinxcontrib-serializinghtml 1.1.5
> > urllib3                       2.4.0
> > ----------------------------- ---------
> >   
> [...]
> 
> > Please compare the versions that you're using on your test
> > environment with the ones I used here.  
> 
> It looks to me like the minimal required version of docutils is 0.17.1
> for PyYAML integration.  Both almalinux:9 and debian:11 have 0.16.
> 
> Sphinx 4.3.2 of Ubuntu 22.04 comes with docutils 0.17.1, and it is
> free of the warnings from PyYAML.

Yes, it seems so. As I commented on my past e-mail, I think we need
a validation logic that will warn if versions are incompatible.
Using the experimental checks you and me did, and checking the minimal
version on Sphinx release notes (*), it seems to be that a good start
point is this:

            ========  ============  ============
            Sphinx    Min Docutils  Max Docutils
            Version   Version       Version
            --------  ------------  ------------
            < 4.0.0   0.17.1        0.17.1
            < 6.0.0   0.17.1        0.18.1
            < 7.0.0   0.18.0        0.18.1
            >= 7.0.0  0.20.0        0.21.2
            ========  ============  ============

Eventually, we may need to blacklist or whitelist other
combinations, but this would require a lot of time.

(*) I asked a LLM AI to check Sphinx release notes and docutils
    versions at the time Sphinx versions were released to aid
    creating such table. I also added your feedback about
    docutils 0.19 and your and my tests with docutils < 0.17.1.

Thanks,
Mauro