Paolo Bonzini <[email protected]> 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
