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

[Akihiko Odaki <akihiko.odaki@daynix.com>]

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