Re: [PATCH] docs: drop the version constraints for sphinx and dependencies

[Vegard Nossum]

On 27/02/2024 14:14, Lukas Bulwahn wrote:
> As discussed (see Links), there is some inertia to move to the recent
> Sphinx versions for the doc build environment.

[...]

> diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
> index 5d47ed443949..1f3b98eee2c9 100644
> --- a/Documentation/sphinx/requirements.txt
> +++ b/Documentation/sphinx/requirements.txt
> @@ -1,6 +1,4 @@
> -# 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
> +jinja2
> +alabaster
> +Sphinx
>   pyyaml

I know you wrote this as well, but just for the record I tried dropping
jinja2 from this list and it still pulled it in automatically:

Collecting Jinja2>=3.0
  Using cached Jinja2-3.1.3-py3-none-any.whl (133 kB)

> diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
> index de0de5dd676e..4c781617ffe6 100755
> --- a/scripts/sphinx-pre-install
> +++ b/scripts/sphinx-pre-install
> @@ -280,8 +280,6 @@ sub get_sphinx_version($)
>   
>   sub check_sphinx()
>   {
> -	my $default_version;
> -
>   	open IN, $conf or die "Can't open $conf";
>   	while (<IN>) {
>   		if (m/^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]/) {
> @@ -293,18 +291,7 @@ sub check_sphinx()
>   
>   	die "Can't get needs_sphinx version from $conf" if (!$min_version);
>   
> -	open IN, $requirement_file or die "Can't open $requirement_file";
> -	while (<IN>) {
> -		if (m/^\s*Sphinx\s*==\s*([\d\.]+)$/) {
> -			$default_version=$1;
> -			last;
> -		}
> -	}
> -	close IN;
> -
> -	die "Can't get default sphinx version from $requirement_file" if (!$default_version);
> -
> -	$virtenv_dir = $virtenv_prefix . $default_version;
> +	$virtenv_dir = $virtenv_prefix . "latest";
>   
>   	my $sphinx = get_sphinx_fname();
>   	if ($sphinx eq "") {
> @@ -318,8 +305,8 @@ sub check_sphinx()
>   	die "$sphinx didn't return its version" if (!$cur_version);
>   
>   	if ($cur_version lt $min_version) {
> -		printf "ERROR: Sphinx version is %s. It should be >= %s (recommended >= %s)\n",
> -		       $cur_version, $min_version, $default_version;
> +		printf "ERROR: Sphinx version is %s. It should be >= %s\n",
> +		       $cur_version, $min_version;
>   		$need_sphinx = 1;
>   		return;
>   	}

Tried with a few different versions:

$ (. sphinx-2.4.4/bin/activate && scripts/sphinx-pre-install)
Detected OS: Ubuntu 22.04.3 LTS.
Sphinx version: 2.4.4


You may also use the newer Sphinx version 7.2.6 with:
        . /home/vegard/linux/sphinx_latest/bin/activate
[...]

$ (. sphinx-2.0/bin/activate && scripts/sphinx-pre-install)
ERROR: Sphinx version is 2.0.0. It should be >= 2.4.4
Detected OS: Ubuntu 22.04.3 LTS.
Sphinx version: 2.0.0


Need to activate Sphinx (version 7.2.6) on virtualenv with:
        . /home/vegard/linux/sphinx_latest/bin/activate
[...]

$ scripts/sphinx-pre-install
Detected OS: Ubuntu 22.04.3 LTS.
Sphinx version: 4.3.2


All optional dependencies are met.
Needed package dependencies are met.


One remark I have is that it didn't encourage me to upgrade to 7.2.6 in
the last one (using the system Sphinx 4.3.2) although it did for the
2.4.4 virtualenv. Maybe that's expected. I didn't look into it. Anyway,
FWIW:

Tested-by: Vegard Nossum <vegard.nossum@xxxxxxxxxx>


Vegard