Re: docs: requirements.txt has stopped working again

[Vegard Nossum <vegard.nossum@oracle.com>]

On 23/01/2024 13:30, Jani Nikula wrote:
> On the other hand, if you're using a virtual environment, what's the
> point in holding back to a version as old as 2.4.4? You might just as
> well go for latest, specifying only the top level dependencies,

Performance... Specifying exact package requirements like 2.4.4 is
useful since 2.4.4 is by far the fastest Sphinx version that builds our
documentation correctly (AFAICT) and build speed matters a lot when the
difference is 10 minutes vs 30 minutes.

> i.e. sphinx and pyyaml. Or you could pip freeze all the requirements at
> a relatively new known good configuration. That's kind of the idea with
> the virtual environment.
> 
> That's really the only two (or three) approaches that make sense to
> me. Using a virtual environment to use ancient versions is just weird.
It makes sense when those ancient versions build our docs just fine and
run MUCH faster too. Here was my proposal, more specifically:

1) requirements.txt : take out all the version constraints so it will
just use the latest versions of everything (unless there are issues with
those) -- this is what I think Akira/Jon/you really want

2) requirements-2.4.4.txt : create this file and add and freeze ALL the
sphinx dependencies at specific versions that make 2.4.4 work --
freezing everything means we should never really need to touch this file
again

3) add a warning when building using slow sphinx versions, perhaps
encouraging people with these slow versions to use
requirements-2.4.4.txt with a virtualenv.

I think this ticks all the boxes:

- No more whack-a-mole (since requirements.txt would have no bounds to
update, and requirements-2.4.4.txt would have everything frozen)

- Doesn't raise the minimum version unnecessarily for people who would
still like to use the older and faster version.


Vegard