[PATCH] Documentation: constrain alabaster package to older versions

[PATCH] Documentation: constrain alabaster package to older versions

[Vegard Nossum]

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(+)

diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
index 335b53df35e2..6b0a981dcb2c 100644
--- a/Documentation/sphinx/requirements.txt
+++ b/Documentation/sphinx/requirements.txt
@@ -1,3 +1,5 @@
 # jinja2>=3.1 is not compatible with Sphinx<4.0
 jinja2<3.1
+# alabaster>=0.7.14 is not compatible with Sphinx<=3.3
+alabaster<0.7.14
 Sphinx==2.4.4
-- 
2.34.1

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

[Jonathan Corbet]

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?

Thanks,

jon

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

[Jonathan Corbet]

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

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

[Vegard Nossum]

On 10/01/2024 16:01, Jonathan Corbet wrote:
> 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?

There is no existing "alabaster" line there -- I'm adding it in with
this patch.

The "alabaster" theme isn't exactly bundled with sphinx per se, it's a
separate package that is depended on by sphinx. So normally when you
install sphinx, it also installs the alabaster package.

Sphinx has this in its pyproject.toml (and has had it since v1.3):

   alabaster>=0.7,<0.8

The problem is that when you install sphinx, it by default gets the most
recent version of alabaster it can find (constrained by the <0.8 above),
which as of two days ago is 0.7.16 -- and is incompatible with Sphinx <=
3.3.

We can fix that by constraining it ourselves to the version before they
dropped Sphinx 3.3 support.

Feel free to amend the changelog if any of that makes it clearer...


Vegard

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

[Bagas Sanjaya]

On Wed, Jan 10, 2024 at 11:46:46AM +0100, Vegard Nossum wrote:
> 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(+)
> 
> diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
> index 335b53df35e2..6b0a981dcb2c 100644
> --- a/Documentation/sphinx/requirements.txt
> +++ b/Documentation/sphinx/requirements.txt
> @@ -1,3 +1,5 @@
>  # jinja2>=3.1 is not compatible with Sphinx<4.0
>  jinja2<3.1
> +# alabaster>=0.7.14 is not compatible with Sphinx<=3.3
> +alabaster<0.7.14
>  Sphinx==2.4.4

LGTM, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

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

[Jonathan Corbet]

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(+)

OK, I'm going to go ahead and apply this, probably for 6.8.

I do think that we need to be thinking about leaving 2.x behind,
performance notwithstanding....experience says that it is just going to
get harder to support over time.  But that's not something to do in a
day, and this is worth fixing now.

Thanks,

jon