Re: [PATCH] Documentation: constrain alabaster package to older versions

[Jonathan Corbet <corbet@lwn.net>]

Jonathan Corbet <corbet@lwn.net> writes:

> Vegard Nossum <vegard.nossum@oracle.com> writes:
>
>> The 'alabaster' theme dropped support for Sphinx < v3.4:
>>
>>     0.7.14 – 2024-01-08
>>
>>     * Dropped support for Python 3.8 and earlier.
>>     * Dropped support for Sphinx 3.3 and earlier.
>>     [...]
>>
>> (Source: https://alabaster.readthedocs.io/en/latest/changelog.html)
>>
>> This manifests as an error when running 'make htmldocs' in a virtualenv
>> constructed from Documentation/sphinx/requirements.txt:
>>
>>     Sphinx version error:
>>     The alabaster extension used by this project needs at least Sphinx v3.4; it therefore cannot be built with this version.
>>
>> Raising the Sphinx version is not really a good option at this point,
>> since 3.x through 6.x have horrible performance regressions (7.x still
>> does, but not quite as bad).
>>
>> Instead, constrain the 'alabaster' package to versions that still support
>> Sphinx 2.4.4.
>>
>> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
>> ---
>>  Documentation/sphinx/requirements.txt | 2 ++
>>  1 file changed, 2 insertions(+)
>
> So this is a little strange, actually.  Alabaster is bundled with
> Sphinx, so there should always be a version that works; I'm not sure why
> we have it separately in the requirements.txt file (which is
> discouraging, given that I probably put it there).
>
> I'll try to look at this (but not right away); do you have any sense for
> whether things work properly if that line is just taken out?

OK, sorry, I've read a bit more closely now.  I'll look into this, but I
really don't think it should be necessary to specify alabaster
explicitly.

If it *is*, then perhaps we should revisit (again) the discussion of
which version of sphinx we're suggesting that people install.

Thanks,

jon