diff mbox series

[PULL,14/16] sphinx: require sphinx 7.2.6

Message ID 20260902193551.582660-15-jsnow@redhat.com
State New
Headers show
Series [PULL,01/16] tests: update vm tests to prefer locally-built QEMU | expand

Commit Message

John Snow Sept. 2, 2026, 7:35 p.m. UTC 
Make the extraordinary leap from Sphinx 3.4.3 to Sphinx
7.2.6. Simplifications and cleanup will follow in subsequent patches.

Note that CentOS Stream 9 only ships a version of Sphinx that runs on
Python 3.9, so regardless of the version of Sphinx we require, if we
require Python 3.10+, CentOS Stream 9 will be unable to build QEMU
documentation in an isolated offline build environment.

CentOS Stream 9 continues to be able to build documentation so long as
PyPI access is permitted during configure, or if the requisite PyPI
packages are installed prior to configure time.

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-ID: <20260825215851.1780608-15-jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/conf.py             |  4 ++--
 docs/requirements.txt    |  2 +-
 python/setup.cfg         |  2 +-
 python/tests/minreqs.txt | 29 ++++++++++++++++-------------
 pythondeps.toml          |  4 ++--
 5 files changed, 22 insertions(+), 19 deletions(-)

Comments

Mark Cave-Ayland Sept. 7, 2026, 12:07 p.m. UTC | #1 
On 02/09/2026 20:35, John Snow wrote:

> Make the extraordinary leap from Sphinx 3.4.3 to Sphinx
> 7.2.6. Simplifications and cleanup will follow in subsequent patches.
> 
> Note that CentOS Stream 9 only ships a version of Sphinx that runs on
> Python 3.9, so regardless of the version of Sphinx we require, if we
> require Python 3.10+, CentOS Stream 9 will be unable to build QEMU
> documentation in an isolated offline build environment.
> 
> CentOS Stream 9 continues to be able to build documentation so long as
> PyPI access is permitted during configure, or if the requisite PyPI
> packages are installed prior to configure time.
> 
> Signed-off-by: John Snow <jsnow@redhat.com>
> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> Message-ID: <20260825215851.1780608-15-jsnow@redhat.com>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>   docs/conf.py             |  4 ++--
>   docs/requirements.txt    |  2 +-
>   python/setup.cfg         |  2 +-
>   python/tests/minreqs.txt | 29 ++++++++++++++++-------------
>   pythondeps.toml          |  4 ++--
>   5 files changed, 22 insertions(+), 19 deletions(-)
> 
> diff --git a/docs/conf.py b/docs/conf.py
> index 7e35d2158d3..cded047b539 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -51,9 +51,9 @@
>   
>   # If your documentation needs a minimal Sphinx version, state it here.
>   #
> -# 3.4.3 is the oldest version of Sphinx that ships on a platform we
> +# 7.2.6 is the oldest version of Sphinx that ships on a platform we
>   # pledge build support for.
> -needs_sphinx = '3.4.3'
> +needs_sphinx = '7.2.6'
>   
>   # Add any Sphinx extension module names here, as strings. They can be
>   # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
> diff --git a/docs/requirements.txt b/docs/requirements.txt
> index 87f7afcb2e7..c10c4cf7c91 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==6.2.1
> +sphinx==7.2.6
>   sphinx_rtd_theme==1.2.2
> diff --git a/python/setup.cfg b/python/setup.cfg
> index ebb4230899c..927f72a46f6 100644
> --- a/python/setup.cfg
> +++ b/python/setup.cfg
> @@ -41,7 +41,7 @@ devel =
>       pylint >= 2.17.3
>       pytest >= 6.2.4
>       tox >= 3.18.0
> -    sphinx >= 3.4.3
> +    sphinx >= 7.2.6
>   
>   # Provides qom-fuse functionality
>   fuse =
> diff --git a/python/tests/minreqs.txt b/python/tests/minreqs.txt
> index 85cfa08cf76..7154ad40040 100644
> --- a/python/tests/minreqs.txt
> +++ b/python/tests/minreqs.txt
> @@ -12,7 +12,7 @@
>   # on PyPI that allows the test suite to pass.
>   
>   # Dependencies for qapidoc/qapi_domain et al
> -sphinx==3.4.3
> +sphinx==7.2.6
>   
>   # Dependencies for qemu.machine
>   qemu.qmp==0.0.6
> @@ -48,23 +48,26 @@ platformdirs==2.2.0
>   tomlkit==0.10.1
>   
>   # Transitive sphinx dependencies
> -Jinja2==2.7
> -MarkupSafe==1.1.0
>   alabaster==0.7.1
> -babel==1.3
> -docutils==0.12
> -imagesize==0.5.0
> -packaging==14.0
> -Pygments==2.0
> -pytz==2014.9
> -requests==2.5.0
> -snowballstemmer==1.1
> +babel==2.9
> +certifi==2023.5.7
> +charset-normalizer==2.0.0
> +docutils==0.18.1
> +idna==2.5
> +imagesize==1.3
> +Jinja2==3.0.0
> +MarkupSafe==2.0
> +packaging==21.0
> +Pygments==2.14
> +requests==2.25.0
> +snowballstemmer==2.0
>   sphinxcontrib-applehelp==1.0.0
>   sphinxcontrib-devhelp==1.0.0
> -sphinxcontrib-htmlhelp==1.0.0
> +sphinxcontrib-htmlhelp==2.0.0
>   sphinxcontrib-jsmath==1.0.0
>   sphinxcontrib-qthelp==1.0.0
> -sphinxcontrib-serializinghtml==1.0.0
> +sphinxcontrib-serializinghtml==1.1.9
> +urllib3==1.26
>   
>   # Transitive pytest dependencies
>   attrs==19.2.0
> diff --git a/pythondeps.toml b/pythondeps.toml
> index b1879c1a4da..f0f3af915a1 100644
> --- a/pythondeps.toml
> +++ b/pythondeps.toml
> @@ -28,8 +28,8 @@ meson = { accepted = ">=1.12.0", installed = "1.12.0", canary = "meson" }
>   
>   [docs]
>   # Please keep the installed versions in sync with docs/requirements.txt
> -sphinx = { accepted = ">=3.4.3", installed = "6.2.1", canary = "sphinx-build" }
> -sphinx_rtd_theme = { accepted = ">=0.5", installed = "1.2.2" }
> +sphinx = { accepted = ">=7.2.6", installed = "7.2.6", canary = "sphinx-build" }
> +sphinx_rtd_theme = { accepted = ">=1.2.2", installed = "1.2.2" }
>   
>   # This test group is for dependencies required to run various tooling
>   # and tests that should always be installed at configure time. It should

Hi John,

This patch appears to break configure with --enable-docs in a fresh 
build/ output directory:

../docs/meson.build:25: WARNING: 
/home/mca/src/upstream/qemu/build/pyvenv/bin/sphinx-build:
Sphinx version error:
This project needs at least Sphinx v7.2.6 and therefore cannot be built 
with this version.


../docs/meson.build:27:6: ERROR: Problem encountered: Install a Python 3 
version of python-sphinx and the readthedoc theme

A full log can be found at 
/home/mca/src/upstream/qemu/build/meson-logs/meson-log.txt

ERROR: meson setup failed

Digging in with a bit more detail we can see that Sphinx 6.2.1 is still 
being installed in the pyvenv:

$ ./build/pyvenv/bin/sphinx-build --version
sphinx-build 6.2.1

And with even more debugging:

$ ./build/pyvenv/bin/python3 -B ./python/scripts/mkvenv.py ensuregroup 
--online ./pythondeps.toml docs
mkvenv: checking for sphinx>=7.2.6
mkvenv: checking for sphinx_rtd_theme>=1.2.2
mkvenv: installing sphinx==7.2.6, sphinx_rtd_theme==1.2.2
ERROR: Cannot install sphinx-rtd-theme==1.2.2 and sphinx==7.2.6 because 
these package versions have conflicting dependencies.
ERROR: ResolutionImpossible: for help visit 
https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts

*** Ouch! ***

Could not provide build dependency 'sphinx==7.2.6':
  • Python package 'sphinx' version '6.2.1' was found, but isn't suitable.
  • A suitable version could not be obtained from PyPI.

If I remove installed = "1.2.2" from pythondeps.toml then that allows 
configure to succeed with sphinx_rtd_theme version 3.1.0 installed, so 
my current workaround is to use the patch below:

diff --git a/pythondeps.toml b/pythondeps.toml
index e4c10d4a9f..84c444ffe8 100644
--- a/pythondeps.toml
+++ b/pythondeps.toml
@@ -29,7 +29,7 @@ meson = { accepted = ">=1.12.0", installed = "1.12.0", 
canary = "meson" }
  [docs]
  # Please keep the installed versions in sync with docs/requirements.txt
  sphinx = { accepted = ">=7.2.6", installed = "7.2.6", canary = 
"sphinx-build" }
-sphinx_rtd_theme = { accepted = ">=1.2.2", installed = "1.2.2" }
+sphinx_rtd_theme = { accepted = ">=1.2.2", installed = "3.1.0" }

  # This test group is for dependencies required to run various tooling
  # and tests that should always be installed at configure time. It should


ATB,

Mark.
Peter Maydell Sept. 7, 2026, 1:13 p.m. UTC | #2 
On Mon, 7 Sept 2026 at 13:07, Mark Cave-Ayland
<mark.caveayland@nutanix.com> wrote:
>
> On 02/09/2026 20:35, John Snow wrote:
>
> > Make the extraordinary leap from Sphinx 3.4.3 to Sphinx
> > 7.2.6. Simplifications and cleanup will follow in subsequent patches.
> >
> > Note that CentOS Stream 9 only ships a version of Sphinx that runs on
> > Python 3.9, so regardless of the version of Sphinx we require, if we
> > require Python 3.10+, CentOS Stream 9 will be unable to build QEMU
> > documentation in an isolated offline build environment.
> >
> > CentOS Stream 9 continues to be able to build documentation so long as
> > PyPI access is permitted during configure, or if the requisite PyPI
> > packages are installed prior to configure time.

> > diff --git a/pythondeps.toml b/pythondeps.toml
> > index b1879c1a4da..f0f3af915a1 100644
> > --- a/pythondeps.toml
> > +++ b/pythondeps.toml
> > @@ -28,8 +28,8 @@ meson = { accepted = ">=1.12.0", installed = "1.12.0", canary = "meson" }
> >
> >   [docs]
> >   # Please keep the installed versions in sync with docs/requirements.txt
> > -sphinx = { accepted = ">=3.4.3", installed = "6.2.1", canary = "sphinx-build" }
> > -sphinx_rtd_theme = { accepted = ">=0.5", installed = "1.2.2" }
> > +sphinx = { accepted = ">=7.2.6", installed = "7.2.6", canary = "sphinx-build" }
> > +sphinx_rtd_theme = { accepted = ">=1.2.2", installed = "1.2.2" }
> >
> >   # This test group is for dependencies required to run various tooling
> >   # and tests that should always be installed at configure time. It should
>
> Hi John,
>
> This patch appears to break configure with --enable-docs in a fresh
> build/ output directory:
>
> ../docs/meson.build:25: WARNING:
> /home/mca/src/upstream/qemu/build/pyvenv/bin/sphinx-build:
> Sphinx version error:
> This project needs at least Sphinx v7.2.6 and therefore cannot be built
> with this version.
>
>
> ../docs/meson.build:27:6: ERROR: Problem encountered: Install a Python 3
> version of python-sphinx and the readthedoc theme

Brian Cain sent a proposed fix for this:
https://patchew.org/QEMU/20260906222926.3714852-1-brian.cain@oss.qualcomm.com/

which is basically the same thing as your workaround.

thanks
-- PMM
diff mbox series

Patch

diff --git a/docs/conf.py b/docs/conf.py
index 7e35d2158d3..cded047b539 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -51,9 +51,9 @@ 
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# 3.4.3 is the oldest version of Sphinx that ships on a platform we
+# 7.2.6 is the oldest version of Sphinx that ships on a platform we
 # pledge build support for.
-needs_sphinx = '3.4.3'
+needs_sphinx = '7.2.6'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 87f7afcb2e7..c10c4cf7c91 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==6.2.1
+sphinx==7.2.6
 sphinx_rtd_theme==1.2.2
diff --git a/python/setup.cfg b/python/setup.cfg
index ebb4230899c..927f72a46f6 100644
--- a/python/setup.cfg
+++ b/python/setup.cfg
@@ -41,7 +41,7 @@  devel =
     pylint >= 2.17.3
     pytest >= 6.2.4
     tox >= 3.18.0
-    sphinx >= 3.4.3
+    sphinx >= 7.2.6
 
 # Provides qom-fuse functionality
 fuse =
diff --git a/python/tests/minreqs.txt b/python/tests/minreqs.txt
index 85cfa08cf76..7154ad40040 100644
--- a/python/tests/minreqs.txt
+++ b/python/tests/minreqs.txt
@@ -12,7 +12,7 @@ 
 # on PyPI that allows the test suite to pass.
 
 # Dependencies for qapidoc/qapi_domain et al
-sphinx==3.4.3
+sphinx==7.2.6
 
 # Dependencies for qemu.machine
 qemu.qmp==0.0.6
@@ -48,23 +48,26 @@  platformdirs==2.2.0
 tomlkit==0.10.1
 
 # Transitive sphinx dependencies
-Jinja2==2.7
-MarkupSafe==1.1.0
 alabaster==0.7.1
-babel==1.3
-docutils==0.12
-imagesize==0.5.0
-packaging==14.0
-Pygments==2.0
-pytz==2014.9
-requests==2.5.0
-snowballstemmer==1.1
+babel==2.9
+certifi==2023.5.7
+charset-normalizer==2.0.0
+docutils==0.18.1
+idna==2.5
+imagesize==1.3
+Jinja2==3.0.0
+MarkupSafe==2.0
+packaging==21.0
+Pygments==2.14
+requests==2.25.0
+snowballstemmer==2.0
 sphinxcontrib-applehelp==1.0.0
 sphinxcontrib-devhelp==1.0.0
-sphinxcontrib-htmlhelp==1.0.0
+sphinxcontrib-htmlhelp==2.0.0
 sphinxcontrib-jsmath==1.0.0
 sphinxcontrib-qthelp==1.0.0
-sphinxcontrib-serializinghtml==1.0.0
+sphinxcontrib-serializinghtml==1.1.9
+urllib3==1.26
 
 # Transitive pytest dependencies
 attrs==19.2.0
diff --git a/pythondeps.toml b/pythondeps.toml
index b1879c1a4da..f0f3af915a1 100644
--- a/pythondeps.toml
+++ b/pythondeps.toml
@@ -28,8 +28,8 @@  meson = { accepted = ">=1.12.0", installed = "1.12.0", canary = "meson" }
 
 [docs]
 # Please keep the installed versions in sync with docs/requirements.txt
-sphinx = { accepted = ">=3.4.3", installed = "6.2.1", canary = "sphinx-build" }
-sphinx_rtd_theme = { accepted = ">=0.5", installed = "1.2.2" }
+sphinx = { accepted = ">=7.2.6", installed = "7.2.6", canary = "sphinx-build" }
+sphinx_rtd_theme = { accepted = ">=1.2.2", installed = "1.2.2" }
 
 # This test group is for dependencies required to run various tooling
 # and tests that should always be installed at configure time. It should