summaryrefslogtreecommitdiffstats
path: root/scripts
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2019-05-29 14:36:41 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2019-05-29 14:36:41 -0700
commitbec7550cca106c3ccc061e3e625516af63054fe4 (patch)
tree2b53e2cb496c0159a4862a91ca2b7f83c562e4df /scripts
parent2b28601d62b01429d12e999fe3712aaf57ca2e26 (diff)
parent551bd3368a7b3cfef01edaade8970948d178d40a (diff)
downloadlinux-bec7550cca106c3ccc061e3e625516af63054fe4.tar.gz
linux-bec7550cca106c3ccc061e3e625516af63054fe4.tar.bz2
linux-bec7550cca106c3ccc061e3e625516af63054fe4.zip
Merge tag 'docs-5.2-fixes2' of git://git.lwn.net/linux
Pull documentation fixes from Jonathan Corbet: "The Sphinx 2.0 release contained a few incompatible API changes that broke our extensions and, thus, the documentation build in general. Who knew that those deprecation warnings it was outputting actually meant we should change something? This set of fixes makes the build work again with Sphinx 2.0 and eliminates the warnings for 1.8. As part of that, we also need a few fixes to the docs for places where the new Sphinx is more strict. It is a bit late in the cycle for this kind of change, but it does fix problems that people are experiencing now. There has been some talk of raising the minimum version of Sphinx we support. I don't want to do that abruptly, though, so these changes add some glue to continue to support versions back to 1.3. We will be adding some infrastructure soon to nudge users of old versions forward, with the idea of maybe increasing our minimum version (and removing this glue) sometime in the future" * tag 'docs-5.2-fixes2' of git://git.lwn.net/linux: drm/i915: Maintain consistent documentation subsection ordering scripts/sphinx-pre-install: make it handle Sphinx versions docs: Fix conf.py for Sphinx 2.0 docs: fix multiple doc build warnings in enumeration.rst lib/list_sort: fix kerneldoc build error docs: fix numaperf.rst and add it to the doc tree doc: Cope with the deprecation of AutoReporter doc: Cope with Sphinx logging deprecations
Diffstat (limited to 'scripts')
-rwxr-xr-xscripts/sphinx-pre-install86
1 files changed, 79 insertions, 7 deletions
diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index f6a5c0bae31e..8c2d1bcf2e02 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";