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

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

This Linux kernel change "scripts/sphinx-pre-install: make it handle Sphinx versions" is included in the Linux 5.2 release. This change is authored by Mauro Carvalho Chehab <mchehab+samsung [at] kernel.org> on Wed May 22 18:43:46 2019 -0300. The commit for this change in Linux stable tree is 77d09ad (patch).

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

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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

There are 86 lines of Linux source code added/deleted in this change. Code changes to Linux kernel are as follows.

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

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index f6a5c0b..8c2d1bc 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,73 @@ 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);
+
+   $virtenv_dir .= $rec_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;
+       }
+       # Sphinx 1.2.x uses a different format
+       if (m/^\s*Sphinx.*\s+([\d\.]+)$/) {
+           $cur_version=$1;
+           last;
+       }
+   }
+   close IN;
+
+   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 +611,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 +625,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";

Leave a Reply

Your email address will not be published. Required fields are marked *