[PATCH 0/2] docs: Bump sphinx to 8.2.3

[PATCH 0/2] docs: Bump sphinx to 8.2.3

[Akihiko Odaki]

Supersedes: <20250120-sphinx-v1-0-65151b4441ac@daynix.com>
("[PATCH 0/2] docs: Bump sphinx to 8.1.3")

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 8.2.3 and also sphinx_rtd_theme as required for the new
sphinx version.

Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.com>
---
Akihiko Odaki (2):
      docs: Bump sphinx to 8.2.3
      MAINTAINERS: Add docs/requirements.txt

 MAINTAINERS           | 1 +
 docs/requirements.txt | 4 ++--
 pythondeps.toml       | 4 ++--
 3 files changed, 5 insertions(+), 4 deletions(-)
---
base-commit: 1da8f3a3c53b604edfe0d55e475102640490549e
change-id: 20250505-sphinx82-ebb3f0bde7d7

Best regards,
-- 
Akihiko Odaki <akihiko.odaki@daynix.com>

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

[Akihiko Odaki]

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 8.2.3 and also sphinx_rtd_theme as required for the new
sphinx version.

Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.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 02583f209aa6..50148c99cbd9 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==8.2.3
+sphinx_rtd_theme==3.0.2
diff --git a/pythondeps.toml b/pythondeps.toml
index c03c9df81b5c..4c0da288be6c 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 = "8.1.3", canary = "sphinx-build" }
+sphinx_rtd_theme = { accepted = ">=0.5", installed = "3.0.2" }
 
 [avocado]
 # Note that qemu.git/python/ is always implicitly installed.

-- 
2.49.0

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

[Akihiko Odaki]

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

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

diff --git a/MAINTAINERS b/MAINTAINERS
index d54b5578f883..6ae5d2665e16 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4328,6 +4328,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.49.0

Re: [PATCH 0/2] docs: Bump sphinx to 8.2.3

[Paolo Bonzini]

On 5/5/25 14:19, Akihiko Odaki wrote:
> Supersedes: <20250120-sphinx-v1-0-65151b4441ac@daynix.com>
> ("[PATCH 0/2] docs: Bump sphinx to 8.1.3")

Sphinx 8 requires Python 3.11 on the other hand; not an objection, just 
a reminder for myself to add a note to the Changelog if this patch is 
merged.

Paolo

> 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 8.2.3 and also sphinx_rtd_theme as required for the new
> sphinx version.
> 
> Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.com>
> ---
> Akihiko Odaki (2):
>        docs: Bump sphinx to 8.2.3
>        MAINTAINERS: Add docs/requirements.txt
> 
>   MAINTAINERS           | 1 +
>   docs/requirements.txt | 4 ++--
>   pythondeps.toml       | 4 ++--
>   3 files changed, 5 insertions(+), 4 deletions(-)
> ---
> base-commit: 1da8f3a3c53b604edfe0d55e475102640490549e
> change-id: 20250505-sphinx82-ebb3f0bde7d7
> 
> Best regards,

Re: [PATCH 0/2] docs: Bump sphinx to 8.2.3

[John Snow]

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

On Mon, May 5, 2025 at 11:36 AM Paolo Bonzini <pbonzini@redhat.com> wrote:

> On 5/5/25 14:19, Akihiko Odaki wrote:
> > Supersedes: <20250120-sphinx-v1-0-65151b4441ac@daynix.com>
> > ("[PATCH 0/2] docs: Bump sphinx to 8.1.3")
>
> Sphinx 8 requires Python 3.11 on the other hand; not an objection, just
> a reminder for myself to add a note to the Changelog if this patch is
> merged.
>

What happens if you are using Python 3.9/3.10 but don't have a suitable
version of Sphinx on hand? I assume it will fail.

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

Re: [PATCH 0/2] docs: Bump sphinx to 8.2.3

[Paolo Bonzini]

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

Il mar 6 mag 2025, 01:06 John Snow <jsnow@redhat.com> ha scritto:

>
>
> On Mon, May 5, 2025 at 11:36 AM Paolo Bonzini <pbonzini@redhat.com> wrote:
>
>> On 5/5/25 14:19, Akihiko Odaki wrote:
>> > Supersedes: <20250120-sphinx-v1-0-65151b4441ac@daynix.com>
>> > ("[PATCH 0/2] docs: Bump sphinx to 8.1.3")
>>
>> Sphinx 8 requires Python 3.11 on the other hand; not an objection, just
>> a reminder for myself to add a note to the Changelog if this patch is
>> merged.
>>
>
> What happens if you are using Python 3.9/3.10 but don't have a suitable
> version of Sphinx on hand? I assume it will fail.
>

Yes, you have to install it yourself (which is what has to be documented in
the release notes).

It does suck that Sphinx doesn't support a version that is perfectly
supported until October 2026, but at least the workaround is simple.

Paolo


>

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

Re: [PATCH 1/2] docs: Bump sphinx to 8.2.3

[John Snow]

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

On Mon, May 5, 2025 at 8:19 AM Akihiko Odaki <akihiko.odaki@daynix.com>
wrote:

> 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 8.2.3 and also sphinx_rtd_theme as required for the new
> sphinx version.
>
> Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.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 02583f209aa6..50148c99cbd9 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==8.2.3
> +sphinx_rtd_theme==3.0.2
>
diff --git a/pythondeps.toml b/pythondeps.toml
> index c03c9df81b5c..4c0da288be6c 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 = "8.1.3", canary =
> "sphinx-build" }
> +sphinx_rtd_theme = { accepted = ">=0.5", installed = "3.0.2" }
>

Can we set our suggested version to 6.2.0 instead? This version removed
reliance on 'imghdr' but merely requires Python 3.8+ which is our current
stated minimum.

If Thomas upgrades our minimum Python to 3.9, then we could use something
as new as 7.2.0 which requires 3.9+.

I'd say 8.0.0 is too new (requires 3.10+) and conflicts with our stated
minimums.


>
>  [avocado]
>  # Note that qemu.git/python/ is always implicitly installed.
>
> --
> 2.49.0
>
>

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

Re: [PATCH 1/2] docs: Bump sphinx to 8.2.3

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Mon, May 5, 2025 at 8:19 AM Akihiko Odaki <akihiko.odaki@daynix.com>
> wrote:
>
>> 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 8.2.3 and also sphinx_rtd_theme as required for the new
>> sphinx version.
>>
>> Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.com>

[...]

> Can we set our suggested version to 6.2.0 instead? This version removed
> reliance on 'imghdr' but merely requires Python 3.8+ which is our current
> stated minimum.
>
> If Thomas upgrades our minimum Python to 3.9, then we could use something
> as new as 7.2.0 which requires 3.9+.

Thomas did: commit d64db833d6.

> I'd say 8.0.0 is too new (requires 3.10+) and conflicts with our stated
> minimums.

Requiring more recent versions of dependencies for optional parts of the
build can be okay, but the degradation must be graceful.

This makes sense only when the more recent dependencies save us enough
trouble to justify inconveniencing users stuck on older dependencies as
well as the additional build system complexity.

I have no opinion on whether that's the case here.  If you think it is,
make your argument :)

"Graceful" means that if we require Sphinx 8, which requires Python
3.10, the build must still succeed when we have only Python 3.9 (our
stated minimum), but we don't build documentation then.  If the user
demands documentation with configure --enable-docs, the build fails.

[...]

Re: [PATCH 1/2] docs: Bump sphinx to 8.2.3

[John Snow]

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

On Wed, May 7, 2025 at 1:22 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > On Mon, May 5, 2025 at 8:19 AM Akihiko Odaki <akihiko.odaki@daynix.com>
> > wrote:
> >
> >> 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 8.2.3 and also sphinx_rtd_theme as required for the new
> >> sphinx version.
> >>
> >> Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.com>
>
> [...]
>
> > Can we set our suggested version to 6.2.0 instead? This version removed
> > reliance on 'imghdr' but merely requires Python 3.8+ which is our current
> > stated minimum.
> >
> > If Thomas upgrades our minimum Python to 3.9, then we could use something
> > as new as 7.2.0 which requires 3.9+.
>
> Thomas did: commit d64db833d6.
>

OK, that being said, let's try setting both the preferred and minimum
versions to *7.2.0*. We could theoretically aim higher, but let's start
conservatively for now and see what, if anything, breaks before we get more
adventurous.

I think 7.2 is new enough that I can remove the vast majority of the
compatibility crud in docs/sphinx/compat.py and it will make my life a lot
easier, without being so new as to require a bleeding edge version of
Python that may not be available on older platforms we still support for
package building.

I think it's not a huge deal to support Sphinx 7.x and 8.x for now. I am
just reluctant to suggest that we should have a pinned (very modern) Sphinx
version for doc building, because I do not know what the impact of that
would be on downstream builds that offer documentation from SRPM (Red Hat,
etc) which may not be able to procure a bleeding-edge Sphinx from PyPI from
an isolated build environment.


> > I'd say 8.0.0 is too new (requires 3.10+) and conflicts with our stated
> > minimums.
>
> Requiring more recent versions of dependencies for optional parts of the
> build can be okay, but the degradation must be graceful.
>
> This makes sense only when the more recent dependencies save us enough
> trouble to justify inconveniencing users stuck on older dependencies as
> well as the additional build system complexity.
>
> I have no opinion on whether that's the case here.  If you think it is,
> make your argument :)
>
> "Graceful" means that if we require Sphinx 8, which requires Python
> 3.10, the build must still succeed when we have only Python 3.9 (our
> stated minimum), but we don't build documentation then.  If the user
> demands documentation with configure --enable-docs, the build fails.
>
> [...]
>
>

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

Re: [PATCH 1/2] docs: Bump sphinx to 8.2.3

[Akihiko Odaki]

On 2025/05/08 3:23, John Snow wrote:
> 
> 
> On Wed, May 7, 2025 at 1:22 AM Markus Armbruster <armbru@redhat.com 
> <mailto:armbru@redhat.com>> wrote:
> 
>     John Snow <jsnow@redhat.com <mailto:jsnow@redhat.com>> writes:
> 
>      > On Mon, May 5, 2025 at 8:19 AM Akihiko Odaki
>     <akihiko.odaki@daynix.com <mailto:akihiko.odaki@daynix.com>>
>      > wrote:
>      >
>      >> 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 8.2.3 and also sphinx_rtd_theme as required for
>     the new
>      >> sphinx version.
>      >>
>      >> Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.com
>     <mailto:akihiko.odaki@daynix.com>>
> 
>     [...]
> 
>      > Can we set our suggested version to 6.2.0 instead? This version
>     removed
>      > reliance on 'imghdr' but merely requires Python 3.8+ which is our
>     current
>      > stated minimum.
>      >
>      > If Thomas upgrades our minimum Python to 3.9, then we could use
>     something
>      > as new as 7.2.0 which requires 3.9+.
> 
>     Thomas did: commit d64db833d6.
> 
> 
> OK, that being said, let's try setting both the preferred and minimum 
> versions to *7.2.0*. We could theoretically aim higher, but let's start 
> conservatively for now and see what, if anything, breaks before we get 
> more adventurous.

7.2.0 as minimum and 7.2.6 as preferred perhaps? Patch releases fix 
regressions so the latest of 7.2.x may have the minimal risk.

> 
> I think 7.2 is new enough that I can remove the vast majority of the 
> compatibility crud in docs/sphinx/compat.py and it will make my life a 
> lot easier, without being so new as to require a bleeding edge version 
> of Python that may not be available on older platforms we still support 
> for package building.
> 
> I think it's not a huge deal to support Sphinx 7.x and 8.x for now. I am 
> just reluctant to suggest that we should have a pinned (very modern) 
> Sphinx version for doc building, because I do not know what the impact 
> of that would be on downstream builds that offer documentation from SRPM 
> (Red Hat, etc) which may not be able to procure a bleeding-edge Sphinx 
> from PyPI from an isolated build environment.
> 
> 
>      > I'd say 8.0.0 is too new (requires 3.10+) and conflicts with our
>     stated
>      > minimums.
> 
>     Requiring more recent versions of dependencies for optional parts of the
>     build can be okay, but the degradation must be graceful.
> 
>     This makes sense only when the more recent dependencies save us enough
>     trouble to justify inconveniencing users stuck on older dependencies as
>     well as the additional build system complexity.
> 
>     I have no opinion on whether that's the case here.  If you think it is,
>     make your argument :)
> 
>     "Graceful" means that if we require Sphinx 8, which requires Python
>     3.10, the build must still succeed when we have only Python 3.9 (our
>     stated minimum), but we don't build documentation then.  If the user
>     demands documentation with configure --enable-docs, the build fails.
> 
>     [...]
>