Em Thu, 19 Jun 2025 10:34:59 +0900
Akira Yokosawa <akiyks@xxxxxxxxx> 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 <akiyks@xxxxxxxxx> 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
