[PATCH 0/2] docs, python: bump sphinx preferred version

[PATCH 0/2] docs, python: bump sphinx preferred version

[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

[PATCH 1/2] docs: Bump sphinx to 6.2.1

[John Snow]

From: Akihiko Odaki <akihiko.odaki@daynix.com>

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

Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.com>
Tested-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/requirements.txt | 4 ++--
 pythondeps.toml       | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 02583f209aa..87f7afcb2e7 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -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
diff --git a/pythondeps.toml b/pythondeps.toml
index 7884ab521d1..b2eec940ce5 100644
--- a/pythondeps.toml
+++ b/pythondeps.toml
@@ -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" }
-- 
2.50.0

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

[John Snow]

From: Akihiko Odaki <akihiko.odaki@daynix.com>

Add docs/requirements.txt to
"Sphinx documentation configuration and build machinery".

Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.com>
Signed-off-by: John Snow <jsnow@redhat.com>
---
 MAINTAINERS | 1 +
 1 file changed, 1 insertion(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index e88ed2c0a97..809cd1aa53c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4426,6 +4426,7 @@ M: Peter Maydell <peter.maydell@linaro.org>
 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
-- 
2.50.0

Re: [PATCH 0/2] docs, python: bump sphinx preferred version

[John Snow]

fwiw, I think this is important enough / harmless enough to sneak into
the rc releases, if possible.

On Tue, Jul 15, 2025 at 5:28 PM John Snow <jsnow@redhat.com> wrote:
>
> 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
>
>

Re: [PATCH 0/2] docs, python: bump sphinx preferred version

[Thomas Huth]

On 16/07/2025 00.20, John Snow wrote:
> 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
Reviewed-by: Thomas Huth <thuth@redhat.com>


> On Tue, Jul 15, 2025 at 5:28 PM John Snow <jsnow@redhat.com> wrote:
>>
>> 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
>>
>>
> 
> 

Re: [PATCH 0/2] docs, python: bump sphinx preferred version

[Markus Armbruster]

Okay to include this in my next QAPI PR?

Re: [PATCH 0/2] docs, python: bump sphinx preferred version

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 302 bytes --]

On Wed, Jul 16, 2025, 11:04 AM Markus Armbruster <armbru@redhat.com> wrote:

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

>

[-- Attachment #2: Type: text/html, Size: 869 bytes --]

Re: [PATCH 0/2] docs, python: bump sphinx preferred version

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Wed, Jul 16, 2025, 11:04 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> 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!