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