docs, python: bump sphinx preferred version
cover docs, python: bump sphinx preferred version
CI: https://gitlab.com/jsnow/qemu/-/pipelines/1928836481
Unlike the previous series, this series only adjusts the *preferred* sphinx version to be higher, leaving the accepted version at 3.4.3, the version that CentOS Stream 9 still ships with.
Unfortunately, this means we can't cut out the compatibility code for sphinx we're still carrying around just yet, but we'll await that glorious moment to arrive on some future day.
Sphinx 6.2.1 is being chosen as the new default because it still offers support for Python 3.8+, but is new enough to support Python 3.13+.
Distro version information for supported platforms as of 2025-07-15:
distro python3 pip setuptools sphinx
-------------------------------------------------------
alpine_3_19 3.11.13 23.3.1 70.3.0 6.2.1 alpine_3_20 3.12.11 24.0 70.3.0 7.2.6 alpine_3_21 3.12.11 24.3.1 70.3.0 8.1.3 alpine_3_22 3.12.11 25.1.1 80.9.0 8.2.3 centos_stream_9 3.9.23 21.3.1 53.0.0 3.4.3 centos_stream_10 3.12.11 23.3.2 69.0.3 7.2.6 debian_12 3.11.2 23.0.1 66.1.1 5.3.0 fedora_41 3.13.5 24.2 69.2.0 7.3.7 fedora_42 3.13.5 24.3.1 74.1.3 8.1.3 freebsd 3.11.13 23.3.2 63.1.0 5.3.0 homebrew 3.13.5 --- 80.9.0 8.2.3 macports 3.13.5 25.1.1 78.1.1 8.2.3 openbsd 3.12.11 25.1.1 79.0.1 8.2.3 pkgsrc_current 3.12.11 25.1.1 80.9.0 8.2.3 ubuntu_22_04 3.10.12 22.0.2 59.6.0 4.3.2 ubuntu_24_04 3.12.3 24.0 68.1.2 7.2.6 ubuntu_24_10 3.12.7 24.2 74.1.2 7.4.7 ubuntu_25_04 3.13.3 25.0 75.8.0 8.1.3
Akihiko Odaki (2):
docs: Bump sphinx to 6.2.1
MAINTAINERS: Add docs/requirements.txt
MAINTAINERS | 1 + docs/requirements.txt | 4 ++-- pythondeps.toml | 4 ++-- 3 files changed, 5 insertions(+), 4 deletions(-)
Signature · 1 line
2.50.0
PATCH 1/2 docs: Bump sphinx to 6.2.1
From: Akihiko Odaki <[email protected]>
sphinx 5.3.0 fails with Python 3.13.1:
../docs/meson.build:37: WARNING: /home/me/qemu/build/pyvenv/bin/sphinx-build:
Extension error:
Could not import extension sphinx.builders.epub3 (exception: No module named 'imghdr')
../docs/meson.build:39:6: ERROR: Problem encountered: Install a Python 3 version of python-sphinx and the readthedoc theme
Bump sphinx to 6.2.1 and also sphinx_rtd_theme as required for the new sphinx version.
(jsnow note: this patch bumps the recommended version for Sphinx to install when it is missing, but allows old versions to be used if they are present and functional. The version used for building docs on readthedocs is pinned to the recommended version, 6.2.1.)
--- docs/requirements.txt | 4 ++-- pythondeps.toml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-)
docs/requirements.txt +2 -2
@@ -1,5 +1,5 @@ # Used by readthedocs.io # Should be in sync with the "installed" key of pythondeps.toml -sphinx==5.3.0 -sphinx_rtd_theme==1.1.1 +sphinx==6.2.1 +sphinx_rtd_theme==1.2.2
pythondeps.toml +2 -2
@@ -24,8 +24,8 @@ pycotap = { accepted = ">=1.1.0", installed = "1.3.1" } [docs] # Please keep the installed versions in sync with docs/requirements.txt -sphinx = { accepted = ">=3.4.3", installed = "5.3.0", canary = "sphinx-build" } -sphinx_rtd_theme = { accepted = ">=0.5", installed = "1.1.1" } +sphinx = { accepted = ">=3.4.3", installed = "6.2.1", canary = "sphinx-build" } +sphinx_rtd_theme = { accepted = ">=0.5", installed = "1.2.2" } [testdeps] qemu.qmp = { accepted = ">=0.0.3", installed = "0.0.3" }
Signature · 1 line
2.50.0
PATCH 2/2 MAINTAINERS: Add docs/requirements.txt
In reply to John SnowFrom: Akihiko Odaki <[email protected]>
Add docs/requirements.txt to
"Sphinx documentation configuration and build machinery".
--- MAINTAINERS | 1 + 1 file changed, 1 insertion(+)
MAINTAINERS +1 -0
@@ -4426,6 +4426,7 @@ M: Peter Maydell <[email protected]> S: Maintained F: docs/conf.py F: docs/*/conf.py +F: docs/requirements.txt F: docs/sphinx/ F: docs/_templates/ F: docs/devel/docs.rst
Signature · 1 line
2.50.0
fwiw, I think this is important enough / harmless enough to sneak into the rc releases, if possible.
Quoted 50 lines · John Snow
CI: https://gitlab.com/jsnow/qemu/-/pipelines/1928836481
Unlike the previous series, this series only adjusts the *preferred* sphinx version to be higher, leaving the accepted version at 3.4.3, the version that CentOS Stream 9 still ships with.
Unfortunately, this means we can't cut out the compatibility code for sphinx we're still carrying around just yet, but we'll await that glorious moment to arrive on some future day.
Sphinx 6.2.1 is being chosen as the new default because it still offers support for Python 3.8+, but is new enough to support Python 3.13+.
Distro version information for supported platforms as of 2025-07-15:
distro python3 pip setuptools sphinx
-------------------------------------------------------alpine_3_19 3.11.13 23.3.1 70.3.0 6.2.1 alpine_3_20 3.12.11 24.0 70.3.0 7.2.6 alpine_3_21 3.12.11 24.3.1 70.3.0 8.1.3 alpine_3_22 3.12.11 25.1.1 80.9.0 8.2.3 centos_stream_9 3.9.23 21.3.1 53.0.0 3.4.3 centos_stream_10 3.12.11 23.3.2 69.0.3 7.2.6 debian_12 3.11.2 23.0.1 66.1.1 5.3.0 fedora_41 3.13.5 24.2 69.2.0 7.3.7 fedora_42 3.13.5 24.3.1 74.1.3 8.1.3 freebsd 3.11.13 23.3.2 63.1.0 5.3.0 homebrew 3.13.5 --- 80.9.0 8.2.3 macports 3.13.5 25.1.1 78.1.1 8.2.3 openbsd 3.12.11 25.1.1 79.0.1 8.2.3 pkgsrc_current 3.12.11 25.1.1 80.9.0 8.2.3 ubuntu_22_04 3.10.12 22.0.2 59.6.0 4.3.2 ubuntu_24_04 3.12.3 24.0 68.1.2 7.2.6 ubuntu_24_10 3.12.7 24.2 74.1.2 7.4.7 ubuntu_25_04 3.13.3 25.0 75.8.0 8.1.3Akihiko Odaki (2):
docs: Bump sphinx to 6.2.1
MAINTAINERS: Adddocs/requirements.txtMAINTAINERS | 1 + docs/requirements.txt | 4 ++-- pythondeps.toml | 4 ++-- 3 files changed, 5 insertions(+), 4 deletions(-)--
2.50.0
Thomas Huth
Reviewed-byQuoted 2 lines · John Snow
fwiw, I think this is important enough / harmless enough to sneak into the rc releases, if possible.
Yes, sounds like a good idea to avoid breakage with the latest Python versions.
Series
Quoted 53 lines · John Snow
Quoted 50 lines
CI: https://gitlab.com/jsnow/qemu/-/pipelines/1928836481
Unlike the previous series, this series only adjusts the *preferred* sphinx version to be higher, leaving the accepted version at 3.4.3, the version that CentOS Stream 9 still ships with.
Unfortunately, this means we can't cut out the compatibility code for sphinx we're still carrying around just yet, but we'll await that glorious moment to arrive on some future day.
Sphinx 6.2.1 is being chosen as the new default because it still offers support for Python 3.8+, but is new enough to support Python 3.13+.
Distro version information for supported platforms as of 2025-07-15:
distro python3 pip setuptools sphinx
-------------------------------------------------------alpine_3_19 3.11.13 23.3.1 70.3.0 6.2.1 alpine_3_20 3.12.11 24.0 70.3.0 7.2.6 alpine_3_21 3.12.11 24.3.1 70.3.0 8.1.3 alpine_3_22 3.12.11 25.1.1 80.9.0 8.2.3 centos_stream_9 3.9.23 21.3.1 53.0.0 3.4.3 centos_stream_10 3.12.11 23.3.2 69.0.3 7.2.6 debian_12 3.11.2 23.0.1 66.1.1 5.3.0 fedora_41 3.13.5 24.2 69.2.0 7.3.7 fedora_42 3.13.5 24.3.1 74.1.3 8.1.3 freebsd 3.11.13 23.3.2 63.1.0 5.3.0 homebrew 3.13.5 --- 80.9.0 8.2.3 macports 3.13.5 25.1.1 78.1.1 8.2.3 openbsd 3.12.11 25.1.1 79.0.1 8.2.3 pkgsrc_current 3.12.11 25.1.1 80.9.0 8.2.3 ubuntu_22_04 3.10.12 22.0.2 59.6.0 4.3.2 ubuntu_24_04 3.12.3 24.0 68.1.2 7.2.6 ubuntu_24_10 3.12.7 24.2 74.1.2 7.4.7 ubuntu_25_04 3.13.3 25.0 75.8.0 8.1.3Akihiko Odaki (2):
docs: Bump sphinx to 6.2.1
MAINTAINERS: Adddocs/requirements.txtMAINTAINERS | 1 + docs/requirements.txt | 4 ++-- pythondeps.toml | 4 ++-- 3 files changed, 5 insertions(+), 4 deletions(-)--
2.50.0
Okay to include this in my next QAPI PR?
Quoted 2 lines · Markus Armbruster
Okay to include this in my next QAPI PR?
That would be very convenient, thank you!
(And thanks to Akihiko Odaki for spotting and fixing the issue, even if it took me a while to sort through our policy.)
Quoted 1 line
Markus Armbruster
AppliedQuoted 9 lines · John Snow
Quoted 2 lines · Markus Armbruster
Okay to include this in my next QAPI PR?
That would be very convenient, thank you!
(And thanks to Akihiko Odaki for spotting and fixing the issue, even if it took me a while to sort through our policy.)
Queued for 10.1. Thanks!