On Wed, May 7, 2025 at 1:22 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@redhat.com> writes: > > > On Mon, May 5, 2025 at 8:19 AM Akihiko Odaki <akihiko.od...@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.od...@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. > > [...] > >
