On Fri, Jun 6, 2025 at 4:50 PM John Snow <jsnow@redhat.com> wrote:
> This is a re-send of Akihiko Odaki's series, rebased and altered to cope
> with the new QAPI static analysis tests now running on GitLab CI.
>
> Changes in this "v1":
>
> - Update python static analysis testing configuration to work with the
> new Sphinx minimum version
> - Small adjustments to qapi_domain.py in light of upstream changes to
> keep new CI tests passing.
> (Thank you for deleting compat.py, Odaki-san!)
> - Make the minimum versions for sphinx and sphinx-rtd-theme more
> explicit, including the patch version number; thiis is *required* for
> Debian platforms which ship sphinx-rtd-theme 1.2.1 and will fail to
> build docs otherwise.
>
> Akihiko Odaki (3):
> docs: Bump sphinx to 6.2.1
> docs: Require sphinx>=6.2
> MAINTAINERS: Add docs/requirements.txt
>
> John Snow (1):
> python: update requirements for Sphinx
>
> MAINTAINERS | 1 +
> docs/requirements.txt | 4 +-
> docs/sphinx/compat.py | 230 -------------------------------------
> docs/sphinx/qapi_domain.py | 38 +++---
> python/setup.cfg | 2 +-
> python/tests/minreqs.txt | 36 +++---
> python/tests/qapi-isort.sh | 4 +-
> pythondeps.toml | 4 +-
> 8 files changed, 46 insertions(+), 273 deletions(-)
> delete mode 100644 docs/sphinx/compat.py
>
> --
> 2.48.1
>
>
Markus is on vacation, so it'd be nice to get some input from some of the
other key maintainers before I take this.
For recap, the issue at hand here is that our preferred version of Sphinx,
5.3.0, is not compatible with Python 3.13 - so if you run configure without
a good Sphinx version, python/scripts/mkvenv.py will attempt to install a
bad version.
This series then does three closely related things:
(1) Update our preferred version of Sphinx to 6.2.1, which should work with
the latest Python versions
(2) Update our *minimum* version of Sphinx to 6.2.1, which allows us to
delete a lot of compatibility crud for Sphinx, which possibly has some
implications for the other Sphinx issues we've been having concerning
duplicate label warnings (I don't know for sure, I haven't tracked that one
as closely.)
(3) Updates the python testing venv to match the above change.
Where I am not fully confident this change will be without problems is the
fact that Debian (and likely some versions of RHEL/SUSE we still support)
do not ship with >= 6.2.1, which may introduce complications for docs in
certain scenarios, particularly for offline/isolated builds of QEMU. Please
refer to my email "Build platform guarantees, docs, tests, and snakes in
the garden" for more detail on concerns there.
Thanks,
--js