diff mbox series

[8/8] scripts/sphinx-pre-install: make it handle Sphinx versions

Message ID 20190522205034.25724-9-corbet@lwn.net
State New
Headers show
Series docs: Fixes for recent versions of Sphinx | expand

Commit Message

Jonathan Corbet May 22, 2019, 8:50 p.m. UTC
From: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>


As we want to switch to a newer Sphinx version in the future,
add some version detected logic, checking if the current
version meets the requirement and suggesting upgrade it the
version is supported but too old.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

---
 scripts/sphinx-pre-install | 81 ++++++++++++++++++++++++++++++++++----
 1 file changed, 74 insertions(+), 7 deletions(-)

-- 
2.21.0

Comments

Mauro Carvalho Chehab May 22, 2019, 9:22 p.m. UTC | #1
Em Wed, 22 May 2019 14:50:34 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> From: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

> 

> As we want to switch to a newer Sphinx version in the future,

> add some version detected logic, checking if the current

> version meets the requirement and suggesting upgrade it the

> version is supported but too old.

> 

> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

> ---

>  scripts/sphinx-pre-install | 81 ++++++++++++++++++++++++++++++++++----

>  1 file changed, 74 insertions(+), 7 deletions(-)

> 

> diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install

> index f6a5c0bae31e..e667db230d0a 100755

> --- a/scripts/sphinx-pre-install

> +++ b/scripts/sphinx-pre-install

> @@ -13,7 +13,7 @@ use strict;

>  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

>  # GNU General Public License for more details.

>  

> -my $virtenv_dir = "sphinx_1.4";

> +my $conf = "Documentation/conf.py";

>  my $requirement_file = "Documentation/sphinx/requirements.txt";

>  

>  #

> @@ -26,7 +26,9 @@ my $need = 0;

>  my $optional = 0;

>  my $need_symlink = 0;

>  my $need_sphinx = 0;

> +my $rec_sphinx_upgrade = 0;

>  my $install = "";

> +my $virtenv_dir = "sphinx_";

>  

>  #

>  # Command line arguments

> @@ -201,13 +203,15 @@ sub check_missing_tex($)

>  	}

>  }

>  

> -sub check_sphinx()

> +sub get_sphinx_fname()

>  {

> -	return if findprog("sphinx-build");

> +	my $fname = "sphinx-build";

> +	return $fname if findprog($fname);

>  

> -	if (findprog("sphinx-build-3")) {

> +	$fname = "sphinx-build-3";

> +	if (findprog($fname)) {

>  		$need_symlink = 1;

> -		return;

> +		return $fname;

>  	}

>  

>  	if ($virtualenv) {

> @@ -219,6 +223,68 @@ sub check_sphinx()

>  	} else {

>  		add_package("python-sphinx", 0);

>  	}

> +

> +	return "";

> +}

> +

> +sub check_sphinx()

> +{

> +	my $min_version;

> +	my $rec_version;

> +	my $cur_version;

> +

> +	open IN, $conf or die "Can't open $conf";

> +	while (<IN>) {

> +		if (m/^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]/) {

> +			$min_version=$1;

> +			last;

> +		}

> +	}

> +	close IN;

> +

> +	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\.]+)$/) {

> +			$rec_version=$1;

> +			last;

> +		}

> +	}

> +	close IN;

> +

> +	die "Can't get recommended sphinx version from $requirement_file" if (!$min_version);

> +

> +	my $sphinx = get_sphinx_fname();

> +	return if ($sphinx eq "");

> +

> +	open IN, "$sphinx --version 2>&1 |" or die "$sphinx returned an error";

> +	while (<IN>) {

> +		if (m/^\s*sphinx-build\s+([\d\.]+)$/) {

> +			$cur_version=$1;

> +			last;

> +		}

> +	}

> +	close IN;

> +

> +	$virtenv_dir .= $rec_version;

> +

> +	die "$sphinx didn't return its version" if (!$cur_version);

> +

> +	printf "Sphinx version %s (minimal: %s, recommended >= %s)\n",

> +		$cur_version, $min_version, $rec_version;

> +

> +	if ($cur_version lt $min_version) {

> +		print "Warning: Sphinx version should be >= $min_version\n\n";

> +		$need_sphinx = 1;

> +		return;

> +	}

> +

> +	if ($cur_version lt $rec_version) {

> +		print "Warning: It is recommended at least Sphinx version $rec_version.\n";

> +		print "         To upgrade, use:\n\n";

> +		$rec_sphinx_upgrade = 1;

> +	}

>  }

>  

>  #

> @@ -540,7 +606,7 @@ sub check_needs()

>  		printf "\tsudo ln -sf %s /usr/bin/sphinx-build\n\n",

>  		       which("sphinx-build-3");

>  	}

> -	if ($need_sphinx) {

> +	if ($need_sphinx || $rec_sphinx_upgrade) {

>  		my $activate = "$virtenv_dir/bin/activate";

>  		if (-e "$ENV{'PWD'}/$activate") {

>  			printf "\nNeed to activate virtualenv with:\n";

> @@ -554,7 +620,8 @@ sub check_needs()

>  			printf "\t$virtualenv $virtenv_dir\n";

>  			printf "\t. $activate\n";

>  			printf "\tpip install -r $requirement_file\n";

> -			$need++;

> +

> +			$need++ if (!$rec_sphinx_upgrade);

>  		}

>  	}

>  	printf "\n";


Please fold this to the patch:

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index e667db230d0a..45427f4289ed 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -255,6 +255,8 @@ sub check_sphinx()
 
 	die "Can't get recommended sphinx version from $requirement_file" if (!$min_version);
 
+	$virtenv_dir .= $rec_version;
+
 	my $sphinx = get_sphinx_fname();
 	return if ($sphinx eq "");
 
@@ -267,8 +269,6 @@ sub check_sphinx()
 	}
 	close IN;
 
-	$virtenv_dir .= $rec_version;
-
 	die "$sphinx didn't return its version" if (!$cur_version);
 
 	printf "Sphinx version %s (minimal: %s, recommended >= %s)\n",


Thanks,
Mauro
Mauro Carvalho Chehab May 22, 2019, 9:44 p.m. UTC | #2
Em Wed, 22 May 2019 18:22:37 -0300
Mauro Carvalho Chehab <mchehab@kernel.org> escreveu:

> Em Wed, 22 May 2019 14:50:34 -0600

> Jonathan Corbet <corbet@lwn.net> escreveu:

> 

> > From: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

> > 

> > As we want to switch to a newer Sphinx version in the future,

> > add some version detected logic, checking if the current

> > version meets the requirement and suggesting upgrade it the

> > version is supported but too old.

> > 

> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

> > Signed-off-by: Jonathan Corbet <corbet@lwn.net>

> > ---

> >  scripts/sphinx-pre-install | 81 ++++++++++++++++++++++++++++++++++----

> >  1 file changed, 74 insertions(+), 7 deletions(-)

> > 

> > diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install

> > index f6a5c0bae31e..e667db230d0a 100755

> > --- a/scripts/sphinx-pre-install

> > +++ b/scripts/sphinx-pre-install

> > @@ -13,7 +13,7 @@ use strict;

> >  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

> >  # GNU General Public License for more details.

> >  

> > -my $virtenv_dir = "sphinx_1.4";

> > +my $conf = "Documentation/conf.py";

> >  my $requirement_file = "Documentation/sphinx/requirements.txt";

> >  

> >  #

> > @@ -26,7 +26,9 @@ my $need = 0;

> >  my $optional = 0;

> >  my $need_symlink = 0;

> >  my $need_sphinx = 0;

> > +my $rec_sphinx_upgrade = 0;

> >  my $install = "";

> > +my $virtenv_dir = "sphinx_";

> >  

> >  #

> >  # Command line arguments

> > @@ -201,13 +203,15 @@ sub check_missing_tex($)

> >  	}

> >  }

> >  

> > -sub check_sphinx()

> > +sub get_sphinx_fname()

> >  {

> > -	return if findprog("sphinx-build");

> > +	my $fname = "sphinx-build";

> > +	return $fname if findprog($fname);

> >  

> > -	if (findprog("sphinx-build-3")) {

> > +	$fname = "sphinx-build-3";

> > +	if (findprog($fname)) {

> >  		$need_symlink = 1;

> > -		return;

> > +		return $fname;

> >  	}

> >  

> >  	if ($virtualenv) {

> > @@ -219,6 +223,68 @@ sub check_sphinx()

> >  	} else {

> >  		add_package("python-sphinx", 0);

> >  	}

> > +

> > +	return "";

> > +}

> > +

> > +sub check_sphinx()

> > +{

> > +	my $min_version;

> > +	my $rec_version;

> > +	my $cur_version;

> > +

> > +	open IN, $conf or die "Can't open $conf";

> > +	while (<IN>) {

> > +		if (m/^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]/) {

> > +			$min_version=$1;

> > +			last;

> > +		}

> > +	}

> > +	close IN;

> > +

> > +	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\.]+)$/) {

> > +			$rec_version=$1;

> > +			last;

> > +		}

> > +	}

> > +	close IN;

> > +

> > +	die "Can't get recommended sphinx version from $requirement_file" if (!$min_version);

> > +

> > +	my $sphinx = get_sphinx_fname();

> > +	return if ($sphinx eq "");

> > +

> > +	open IN, "$sphinx --version 2>&1 |" or die "$sphinx returned an error";

> > +	while (<IN>) {

> > +		if (m/^\s*sphinx-build\s+([\d\.]+)$/) {

> > +			$cur_version=$1;

> > +			last;

> > +		}

> > +	}

> > +	close IN;

> > +

> > +	$virtenv_dir .= $rec_version;

> > +

> > +	die "$sphinx didn't return its version" if (!$cur_version);

> > +

> > +	printf "Sphinx version %s (minimal: %s, recommended >= %s)\n",

> > +		$cur_version, $min_version, $rec_version;

> > +

> > +	if ($cur_version lt $min_version) {

> > +		print "Warning: Sphinx version should be >= $min_version\n\n";

> > +		$need_sphinx = 1;

> > +		return;

> > +	}

> > +

> > +	if ($cur_version lt $rec_version) {

> > +		print "Warning: It is recommended at least Sphinx version $rec_version.\n";

> > +		print "         To upgrade, use:\n\n";

> > +		$rec_sphinx_upgrade = 1;

> > +	}

> >  }

> >  

> >  #

> > @@ -540,7 +606,7 @@ sub check_needs()

> >  		printf "\tsudo ln -sf %s /usr/bin/sphinx-build\n\n",

> >  		       which("sphinx-build-3");

> >  	}

> > -	if ($need_sphinx) {

> > +	if ($need_sphinx || $rec_sphinx_upgrade) {

> >  		my $activate = "$virtenv_dir/bin/activate";

> >  		if (-e "$ENV{'PWD'}/$activate") {

> >  			printf "\nNeed to activate virtualenv with:\n";

> > @@ -554,7 +620,8 @@ sub check_needs()

> >  			printf "\t$virtualenv $virtenv_dir\n";

> >  			printf "\t. $activate\n";

> >  			printf "\tpip install -r $requirement_file\n";

> > -			$need++;

> > +

> > +			$need++ if (!$rec_sphinx_upgrade);

> >  		}

> >  	}

> >  	printf "\n";  

> 

> Please fold this to the patch:

> 

> diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install

> index e667db230d0a..45427f4289ed 100755

> --- a/scripts/sphinx-pre-install

> +++ b/scripts/sphinx-pre-install

> @@ -255,6 +255,8 @@ sub check_sphinx()

>  

>  	die "Can't get recommended sphinx version from $requirement_file" if (!$min_version);

>  

> +	$virtenv_dir .= $rec_version;

> +

>  	my $sphinx = get_sphinx_fname();

>  	return if ($sphinx eq "");

>  

> @@ -267,8 +269,6 @@ sub check_sphinx()

>  	}

>  	close IN;

>  

> -	$virtenv_dir .= $rec_version;

> -

>  	die "$sphinx didn't return its version" if (!$cur_version);

>  

>  	printf "Sphinx version %s (minimal: %s, recommended >= %s)\n",

> 

> 

> Thanks,

> Mauro


Found another issue when trying to run it with Sphinx 1.2. Just sent
a version 2 with this fix, plus the version detection for very old
Sphinx versions.

Thanks,
Mauro
diff mbox series

Patch

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index f6a5c0bae31e..e667db230d0a 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -13,7 +13,7 @@  use strict;
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 
-my $virtenv_dir = "sphinx_1.4";
+my $conf = "Documentation/conf.py";
 my $requirement_file = "Documentation/sphinx/requirements.txt";
 
 #
@@ -26,7 +26,9 @@  my $need = 0;
 my $optional = 0;
 my $need_symlink = 0;
 my $need_sphinx = 0;
+my $rec_sphinx_upgrade = 0;
 my $install = "";
+my $virtenv_dir = "sphinx_";
 
 #
 # Command line arguments
@@ -201,13 +203,15 @@  sub check_missing_tex($)
 	}
 }
 
-sub check_sphinx()
+sub get_sphinx_fname()
 {
-	return if findprog("sphinx-build");
+	my $fname = "sphinx-build";
+	return $fname if findprog($fname);
 
-	if (findprog("sphinx-build-3")) {
+	$fname = "sphinx-build-3";
+	if (findprog($fname)) {
 		$need_symlink = 1;
-		return;
+		return $fname;
 	}
 
 	if ($virtualenv) {
@@ -219,6 +223,68 @@  sub check_sphinx()
 	} else {
 		add_package("python-sphinx", 0);
 	}
+
+	return "";
+}
+
+sub check_sphinx()
+{
+	my $min_version;
+	my $rec_version;
+	my $cur_version;
+
+	open IN, $conf or die "Can't open $conf";
+	while (<IN>) {
+		if (m/^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]/) {
+			$min_version=$1;
+			last;
+		}
+	}
+	close IN;
+
+	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\.]+)$/) {
+			$rec_version=$1;
+			last;
+		}
+	}
+	close IN;
+
+	die "Can't get recommended sphinx version from $requirement_file" if (!$min_version);
+
+	my $sphinx = get_sphinx_fname();
+	return if ($sphinx eq "");
+
+	open IN, "$sphinx --version 2>&1 |" or die "$sphinx returned an error";
+	while (<IN>) {
+		if (m/^\s*sphinx-build\s+([\d\.]+)$/) {
+			$cur_version=$1;
+			last;
+		}
+	}
+	close IN;
+
+	$virtenv_dir .= $rec_version;
+
+	die "$sphinx didn't return its version" if (!$cur_version);
+
+	printf "Sphinx version %s (minimal: %s, recommended >= %s)\n",
+		$cur_version, $min_version, $rec_version;
+
+	if ($cur_version lt $min_version) {
+		print "Warning: Sphinx version should be >= $min_version\n\n";
+		$need_sphinx = 1;
+		return;
+	}
+
+	if ($cur_version lt $rec_version) {
+		print "Warning: It is recommended at least Sphinx version $rec_version.\n";
+		print "         To upgrade, use:\n\n";
+		$rec_sphinx_upgrade = 1;
+	}
 }
 
 #
@@ -540,7 +606,7 @@  sub check_needs()
 		printf "\tsudo ln -sf %s /usr/bin/sphinx-build\n\n",
 		       which("sphinx-build-3");
 	}
-	if ($need_sphinx) {
+	if ($need_sphinx || $rec_sphinx_upgrade) {
 		my $activate = "$virtenv_dir/bin/activate";
 		if (-e "$ENV{'PWD'}/$activate") {
 			printf "\nNeed to activate virtualenv with:\n";
@@ -554,7 +620,8 @@  sub check_needs()
 			printf "\t$virtualenv $virtenv_dir\n";
 			printf "\t. $activate\n";
 			printf "\tpip install -r $requirement_file\n";
-			$need++;
+
+			$need++ if (!$rec_sphinx_upgrade);
 		}
 	}
 	printf "\n";