Skip to contentSkip to conversation

docs, python: bump sphinx preferred version

PATCH Applied John Snow 3 participants 8 messages Jul 15, 2025 – Jul 16, 2025

lore
Share & tools
lore

John Snow

author
#0 lore raw

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
author
#1 lore raw

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
index 02583f209aa..87f7afcb2e7 100644
@@ -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
index 7884ab521d1..b2eec940ce5 100644
@@ -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
author
#2 lore raw

PATCH 2/2 MAINTAINERS: Add docs/requirements.txt

In reply to John Snow

From: 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
index e88ed2c0a97..809cd1aa53c 100644
@@ -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
author
#3 lore raw
In reply to John Snow

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.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(-)

--
2.50.0

Reviewed-by
#4 lore raw
Quoted 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.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(-)

--
2.50.0

author
#6 lore raw
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
#7 lore raw
Quoted 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!