From 9b88ad5464af1bf7228991f1c46a9a13484790a4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 29 May 2019 20:09:26 -0300 Subject: [PATCH] scripts/sphinx-pre-install: always check if version is compatible with build Call the script every time a make docs target is selected, on a simplified check mode. With this change, the script will set two vars: $min_version - obtained from `needs_sphinx` var inside conf.py (currently, '1.3') $rec_version - obtained from sphinx/requirements.txt. With those changes, a target like "make htmldocs" will do: 1) If no sphinx-build/sphinx-build3 is found, it will run the script on normal mode as before, checking for all system dependencies and providing install hints for the needed programs and will abort the build; 2) If no sphinx-build/sphinx-build3 is found, but there is a sphinx_${VER}/bin/activate file, and if ${VER} >= $min_version (string comparation), it will run in full mode, and will recommend to activate the virtualenv. If there are multiple virtualenvs, it will string sort the versions, recommending the highest version and will abort the build; 3) If Sphinx is detected but has a version lower than $min_version, it will run in full mode - with will recommend creating a virtual env using sphinx/requirements.txt, and will abort the build. 4) If Sphinx is detected and version is lower than $rec_version, it will run in full mode and will recommend creating a virtual env using sphinx/requirements.txt. In this case, it **won't** abort the build. 5) If Sphinx is detected and version is equal or righer than $rec_version it will return just after detecting the version ("quick mode"), not checking if are there any missing dependencies. Just like before, if one wants to install Sphinx from the distro, it has to call the script manually and use `--no-virtualenv` argument to get the hints for his OS: You should run: sudo dnf install -y python3-sphinx python3-sphinx_rtd_theme While here, add a small help for the three optional arguments for the script. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/Makefile | 5 +++++ scripts/sphinx-pre-install | 40 +++++++++++++++++++++++++------------- 2 files changed, 32 insertions(+), 13 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index e889e7cb8511..380e24053d6f 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -70,12 +70,14 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) $(abspath $(BUILDDIR)/$3/$4) htmldocs: + @./scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) linkcheckdocs: @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var))) latexdocs: + @./scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) ifeq ($(HAVE_PDFLATEX),0) @@ -87,14 +89,17 @@ pdfdocs: else # HAVE_PDFLATEX pdfdocs: latexdocs + @./scripts/sphinx-pre-install --version-check $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;) endif # HAVE_PDFLATEX epubdocs: + @./scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) xmldocs: + @./scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) endif # HAVE_SPHINX diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index ded3e2ef3f8d..f001fc2fcf12 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -38,6 +38,7 @@ my $min_version; my $pdf = 1; my $virtualenv = 1; +my $version_check = 0; # # List of required texlive packages on Fedora and OpenSuse @@ -277,20 +278,22 @@ sub check_sphinx() 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"; + printf "ERROR: Sphinx version is %s. It should be >= %s (recommended >= %s)\n", + $cur_version, $min_version, $rec_version;; $need_sphinx = 1; return; } if ($cur_version lt $rec_version) { + printf "Sphinx version %s\n", $cur_version; print "Warning: It is recommended at least Sphinx version $rec_version.\n"; - print " To upgrade, use:\n\n"; $rec_sphinx_upgrade = 1; + return; } + + # On version check mode, just assume Sphinx has all mandatory deps + exit (0) if ($version_check); } # @@ -575,14 +578,18 @@ sub check_distros() sub check_needs() { + # Check for needed programs/tools + check_sphinx(); + if ($system_release) { - print "Detected OS: $system_release.\n"; + print "Detected OS: $system_release.\n\n"; } else { - print "Unknown OS\n"; + print "Unknown OS\n\n"; } + print "To upgrade Sphinx, use:\n\n" if ($rec_sphinx_upgrade); + # Check for needed programs/tools - check_sphinx(); check_perl_module("Pod::Usage", 0); check_program("make", 0); check_program("gcc", 0); @@ -601,13 +608,14 @@ sub check_needs() } if ($need_sphinx || $rec_sphinx_upgrade) { my $min_activate = "$ENV{'PWD'}/${virtenv_prefix}${min_version}/bin/activate"; - my @activates = glob "$ENV{'PWD'}/${virtenv_prefix}*/bin/activate"; + my @activates = glob "$ENV{'PWD'}/${virtenv_prefix}*/bin/activate"; - @activates = sort {$b cmp $a} @activates; + @activates = sort {$b cmp $a} @activates; - if (scalar @activates > 0 && $activates[0] ge $min_activate) { - printf "\nNeed to activate virtualenv with:\n"; + if ($need_sphinx && scalar @activates > 0 && $activates[0] ge $min_activate) { + printf "\nNeed to activate a compatible Sphinx version on virtualenv with:\n"; printf "\t. $activates[0]\n"; + exit (1); } else { my $rec_activate = "$virtenv_dir/bin/activate"; my $virtualenv = findprog("virtualenv-3"); @@ -646,8 +654,14 @@ while (@ARGV) { $virtualenv = 0; } elsif ($arg eq "--no-pdf"){ $pdf = 0; + } elsif ($arg eq "--version-check"){ + $version_check = 1; } else { - print "Usage:\n\t$0 <--no-virtualenv> <--no-pdf>\n\n"; + print "Usage:\n\t$0 <--no-virtualenv> <--no-pdf> <--version-check>\n\n"; + print "Where:\n"; + print "\t--no-virtualenv\t- Recommend installing Sphinx instead of using a virtualenv\n"; + print "\t--version-check\t- if version is compatible, don't check for missing dependencies\n"; + print "\t--no-pdf\t- don't check for dependencies required to build PDF docs\n\n"; exit -1; } } -- 2.30.2