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