On Mon, Sep 30, 2024 at 01:16:42PM -0400, John Snow wrote: > Hi, following up from my KVM forum talk ( > https://www.youtube.com/watch?v=GGbz3WwvqLw ) I wanted to ask about what > version of Sphinx we could use as a minimum version to help ease the burden > of modernizing our QMP docs without a long backwards compatibility tail > (and hundreds of lines of compatibility goop to make it happen.) > > First, some necessary background on the current state of our Python > environment and build system: > > Paolo and I worked on a Python virtual environment tied to the QEMU build > system (python/scripts/mkvenv.py) which performs various setup actions > necessary to instantiate python *stuff* to ensure the build works and is > always using the correct, configured Python interpreter. > > Currently, configure will invoke mkvenv in such a fashion that it prefers > any local packages you have installed: notably, meson, sphinx, and > sphinx-rtd-theme if you already have them installed from your distro's > repository will be used *if they use the version of python you specified to > configure* (or they match the version that configure guessed if you didn't > specify one.) > > For meson, if you don't meet the minimum version, we will install a version > for you from our vendored whl files in the repository/tarball. > > For sphinx, if you don't meet the minimum version and you have specified > --enable-docs, we'll install a version from the internet, from PyPI. If you > did not specify --enable-docs, we disable docs. > > We did it this way because: > - It's *really fast* if you already have the dependencies you need > - meson is easy to vendor as a .whl because it's pure python, has *zero* > dependencies, and it's absolutely required for the build. > - docs are not *required* to build QEMU > - We went out of our way to ensure that QEMU could be built in an offline, > isolated environment on all of our supported platforms. > > That being said: > > The current reality is that Sphinx 3.4.3 is our minimum because RHEL 9 > offers that as the distro package and I have not dared bump our version > beyond that for fear of disrupting our ability to build docs on RHEL 9 > without internet. > > What I'd like to ask is: How adamant are we that we can build docs on older > platforms? Do we consider it part of our platform promise? Can we bump > Sphinx to a slightly newer version at the expense of offline doc builds for > RHEL 9?
As you say, with meson, if the distro does not provide a new enough version, then we pull a suitable version into the venv, overriding what the distro provides. IMHO that has set a precedent for /any/ python component we need during build. To put it another way.... The distro build platform matrix rules *only* apply to python runtime, not to python modules. We will bump the min version of python modules as suits QEMU, without being held back by distro versions. With this POV, there is nothing special about sphinx. If we want to bump min sphinx to get a newer version, then we should just do it. The only important bit is that our tool for populating the venv must "do the right thing" detecting that the distro version is too old, and downloading newer sphinx automatically, so users don't suddenly loose docs. With regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
