Re: Build platform guarantees, docs, tests, and snakes in the garden

[Markus Armbruster <armbru@redhat.com>]

Paolo Bonzini <pbonzini@redhat.com> writes:

> On 6/5/25 21:35, John Snow wrote:
>> However, if we take as iron-clad our commitment to the build platform promise -- *and* guarantee offline/tarball builds as well -- then Debian 12 (as an example) only offers Sphinx 5.3.0 and not newer unless we allow internet access to fetch Sphinx 6.2.1. This is not a problem for developer workstations at all, but I am unclear on what problems this may cause for tarball releases and downstream offline/isolated/ reproducible builds, if any.
>> In this case, we can (probably) "fix" the issue by continuing to allow older Sphinx while preferring a newer Sphinx version when it is missing, but then we lose the ability to make code cleanups and drop a lot of back-compat crud. If memory serves, there were other issues recently where older versions of Sphinx behaved differently from newer versions, causing intermittent failures that were hard to track down.
>
> The *ideal* solution would be to:
>
> - accept: 4.3.2 or newer, which is what Ubuntu 22.04 has
>
> - install: 6.2.1, which is what supports Python 3.13

I guess this relates to pythondeps.toml line

    sphinx = { accepted = ">=3.4.3", installed = "5.3.0", canary = "sphinx-build" }

I further guess "accepted" means "reject anything older", and
"installed" means "preferred version".

> This lets all supported distros build documentation if they use the default Python runtime.  It would still require a couple hacks in compat.py: SOURCE_LOCATION_FIX and nested_parse_with_titles().
>
> I am not sure however whether to count the latter, for two reasons. First, it has this:
>
>     # necessary so that the child nodes get the right source/line set
>     content_node.document = directive.state.document
>
> so it is not a pure compatibility hack.  Second, and opposite, currently none of the uses of nested_parse_with_titles() go through compat.py's version, therefore it probably can be removed altogether.
>
> That leaves only SOURCE_LOCATION_FIX.
>
> As an aside, if the compat.py hacks survive, I would add comments to document which distros need the hacks.
>
>> What I'd like to know is: what precisely are our options in this scenario? Do we consider it acceptable for some platforms to be unable to build docs offline?
>
> Certainly for platforms not using the default Python runtime, which right now is only SLES.  For others...
>
>> How highly do we value the ability to locally build docs for any given release?

Purely offline, or not?

> ... I think I value this a bit higher than Markus, but not really because of offline builds.  Rather, keeping the "accepted" key lower (i.e. supporting the packaged sphinx on a wide range of distros) makes it easier to bump the "installed" key when needed, as in this failure to run 5.3.0 under Python 3.13.

Showing my ignorance again...  I don't understand how keeping "accepted"
lower helps.

> This time there was a version that works on both the oldest and newest Python that we support, but there may not always be one because sphinx is all too happy at dropping support for EOL'd versions of Python.

Pretty strong hint we shouldn't try to support EOL'd versions of Python
either.

> Paolo
>
>> Before I throw my weight behind any given option, I just want to know what we consider our non-negotiable obligations to be.
>> Thanks,
>> --js