Re: docs: requirements.txt has stopped working again

[Jani Nikula <jani.nikula@linux.intel.com>]

On Tue, 23 Jan 2024, Vegard Nossum <vegard.nossum@oracle.com> wrote:
> On 23/01/2024 05:14, Akira Yokosawa wrote:
>> Hi all,
>> 
>> Annoyingly, installing Sphinx 2.4.4 using requirements.txt of v6.8-rc1
>> ends up in a run-time error which looks similar to the one Vegard
>> reported in commit f4cac0f74658 ("Documentation: constrain alabaster
>> package to older versions").
>> 
>> The new error is from sphinxcontrib.applehelp which reads:
>> 
>>      Sphinx version error:
>>      The sphinxcontrib.applehelp extension used by this project needs
>>      at least Sphinx v5.0; it therefore cannot be built with this version.
>> 
>> Do we want to continue whack-a-mole update for Sphinx 2.4.4?
>> 
>>          Thanks, Akira
>
> Can we have requirements(-latest).txt and requirements-2.4.4.txt?
>
> The thing is, we are not using new features of Sphinx in the kernel
> docs. We don't fundamentally require a new version in any of our .rst
> files or markup, these aren't security issues being fixed or bugs that
> we've run into, the problem is purely that we are using a software
> ecosystem that apparently has no restraint when it comes to breaking
> their users.

We do use at least namespacing which was new to Sphinx 3.1. And we could
use more if we weren't so conservative about the versions.

> My issue with _requiring_ newer versions of Sphinx is the fact that they
> have performance regressions: 4.3.2 takes 3x longer to run than 2.4.4 on
> my laptop. You need to go all the way up to 7.x in order to back to
> reasonable performance -- and that will probably be too new to support
> most of the distro-packaged Sphinxes.
>
> If we have two or more requirements*.txt files, we could just freeze ALL
> the dependencies for 2.4.4 at versions that we know to work. That should
> stop the whack-a-mole for that version. And then we don't have to force
> everybody on to newer/slower versions.
>
> I mean, I can also maintain my own requirements-2.4.4.txt on my local
> filesystem but I think it's better to do the right thing out of the box
> for all users, no? Maybe we should also add in warnings about the
> known-slow Sphinx versions.

If you're using distro-packaged Sphinx, or use pip system/user install,
specifying exact package requirements like 2.4.4 does not really make
sense to me. I don't want kernel requirements to interfere with whatever
else I'm doing. You should just specify the minimum Sphinx version using
needs_sphinx in conf.py, maybe based on [1].

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


BR,
Jani.


[1] https://lore.kernel.org/r/a445d391-4cc9-4d6d-85ad-02d23aa57ebb@gmail.com

-- 
Jani Nikula, Intel