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

[Markus Armbruster <armbru@redhat.com>]

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.

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

[...]