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

[John Snow <jsnow@redhat.com>]

[-- 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 --]