From d14d0c1aea8fe0eb61b7788a3b546475e183b079 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 14 Apr 2020 18:56:08 +0200 Subject: scripts: sphinx-pre-install: improve distro detection check The Arch-linux detection is hit by catting /etc/issue, whose contents is (nowadays): Arch Linux \r (\l) It sounds a little ackward to print such string, so, instead, let's use the /etc/os-release file, with exists on lots of distributions and should provide a more reliable result. We'll keep the old tests before it, in order to avoid possible regressions with the other distros, although the new way should probably work on all the currently supported distributions. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/472924557afdf2b5492ae2a48c5ecfae216d54e2.1586883286.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index fa3fb05cd54b..ea941c6e0647 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -780,6 +780,24 @@ $system_release = catcheck("/etc/system-release") if !$system_release; $system_release = catcheck("/etc/redhat-release") if !$system_release; $system_release = catcheck("/etc/lsb-release") if !$system_release; $system_release = catcheck("/etc/gentoo-release") if !$system_release; + +# This seems more common than LSB these days +if (!$system_release) { + my %os_var; + if (open IN, "cat /etc/os-release|") { + while () { + if (m/^([\w\d\_]+)=\"?([^\"]*)\"?\n/) { + $os_var{$1}=$2; + } + } + $system_release = $os_var{"NAME"}; + if (defined($os_var{"VERSION_ID"})) { + $system_release .= " " . $os_var{"VERSION_ID"} if (defined($os_var{"VERSION_ID"})); + } else { + $system_release .= " " . $os_var{"VERSION"}; + } + } +} $system_release = catcheck("/etc/issue") if !$system_release; $system_release =~ s/\s+$//; -- cgit v1.3 From b3df6223bdea763ed666b06a4e7431f40b33da67 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 14 Apr 2020 18:56:09 +0200 Subject: scripts: sphinx-pre-install: improve openSuse Tumbleweed check Currently, with openSUSE Tumbleweed 20200303, it keeps recommending this forever: sudo zypper install --no-recommends rsvg-view This dependency will never be fulfilled there, as the package now is named as on other distros: rsvg-convert. So, improve the detection to avoid such issue. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/c3774f72ac36c5e5b5f446ae5db5b795d1f274f4.1586883286.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index ea941c6e0647..6d6d2849fbb1 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -446,9 +446,11 @@ sub give_opensuse_hints() "convert" => "ImageMagick", "Pod::Usage" => "perl-Pod-Usage", "xelatex" => "texlive-xetex-bin", - "rsvg-convert" => "rsvg-view", ); + # On Tumbleweed, this package is also named rsvg-convert + $map{"rsvg-convert"} = "rsvg-view" if (!($system_release =~ /Tumbleweed/)); + my @suse_tex_pkgs = ( "texlive-babel-english", "texlive-caption", -- cgit v1.3 From bfc7f4281066154e6b420a87335d6387c9b0835a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 14 Apr 2020 18:56:10 +0200 Subject: scripts: sphinx-pre-install: fix a dependency hint with Ubuntu 16.04 Avoid the scripts to keep asking to install fonts-noto-cjk on Ubuntu 16.04. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/912b664a8ca54e8c5c5767c3fe9171973eeddd6b.1586883286.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 6d6d2849fbb1..ba750f7b9127 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -349,7 +349,8 @@ sub give_debian_hints() "fonts-dejavu", 2); check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc", - "/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc"], + "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc", + "/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc"], "fonts-noto-cjk", 2); } -- cgit v1.3 From e45a631742fadd7c9feb5a0049382102e5d43fe7 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 14 Apr 2020 18:56:11 +0200 Subject: scripts: sphinx-pre-install: address some issues with Gentoo There are some small misdetections with Gentoo. While they don't cause too much trouble, it keeps recomending to install things that are already there. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/7f631edce102b02ccbdbfb18be1376a86b41373d.1586883286.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index ba750f7b9127..86e14b9fd537 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -560,7 +560,8 @@ sub give_gentoo_hints() "media-fonts/dejavu", 2) if ($pdf); if ($pdf) { - check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf"], + check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf", + "/usr/share/fonts/noto-cjk/NotoSerifCJK-Regular.ttc"], "media-fonts/noto-cjk", 2); } @@ -575,10 +576,10 @@ sub give_gentoo_hints() my $portage_imagemagick = "/etc/portage/package.use/imagemagick"; my $portage_cairo = "/etc/portage/package.use/graphviz"; - if (qx(cat $portage_imagemagick) ne "$imagemagick\n") { + if (qx(grep imagemagick $portage_imagemagick 2>/dev/null) eq "") { printf("\tsudo su -c 'echo \"$imagemagick\" > $portage_imagemagick'\n") } - if (qx(cat $portage_cairo) ne "$cairo\n") { + if (qx(grep graphviz $portage_cairo 2>/dev/null) eq "") { printf("\tsudo su -c 'echo \"$cairo\" > $portage_cairo'\n"); } -- cgit v1.3 From d6ebf1890c8ba6c9340681cb24bdbdb0ea7c71b4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 14 Apr 2020 18:56:12 +0200 Subject: scripts: sphinx-pre-install: add support for OpenMandriva It seems that Mageia and OpenMandriva will reunite on a single distribution. In any case, both came from Mandriva. So, it is close enough to use the same logic. So, add support for it. Tested with OpenMandriva 4.1 and with Mageia 7.1. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/692809729c6818a0b0f75513da15970c53d5565c.1586883286.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 86e14b9fd537..89b033285caf 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -494,7 +494,7 @@ sub give_mageia_hints() "convert" => "ImageMagick", "Pod::Usage" => "perl-Pod-Usage", "xelatex" => "texlive", - "rsvg-convert" => "librsvg2-tools", + "rsvg-convert" => "librsvg2", ); my @tex_pkgs = ( @@ -503,16 +503,29 @@ sub give_mageia_hints() $map{"latexmk"} = "texlive-collection-basic"; + my $packager_cmd; + my $noto_sans; + if ($system_release =~ /OpenMandriva/) { + $packager_cmd = "dnf install"; + $noto_sans = "noto-sans-cjk-fonts"; + @tex_pkgs = ( "texlive-collection-fontsextra" ); + } else { + $packager_cmd = "urpmi"; + $noto_sans = "google-noto-sans-cjk-ttc-fonts"; + } + + if ($pdf) { - check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc"], - "google-noto-sans-cjk-ttc-fonts", 2); + check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc", + "/usr/share/fonts/TTF/NotoSans-Regular.ttf"], + $noto_sans, 2); } check_rpm_missing(\@tex_pkgs, 2) if ($pdf); check_missing(\%map); return if (!$need && !$optional); - printf("You should run:\n\n\tsudo urpmi $install\n"); + printf("You should run:\n\n\tsudo $packager_cmd $install\n"); } sub give_arch_linux_hints() @@ -626,6 +639,10 @@ sub check_distros() give_mageia_hints; return; } + if ($system_release =~ /OpenMandriva/) { + give_mageia_hints; + return; + } if ($system_release =~ /Arch Linux/) { give_arch_linux_hints; return; -- cgit v1.3 From 2f9c502552cd3e791db91ee80f7766e122b3b026 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 14 Apr 2020 18:56:13 +0200 Subject: scripts: sphinx-pre-install: add support for python -m venv Since python 3.3, the recommended way to setup a virtual env is via "python -m venv". Set this as a default, if python version is compatible with such feature. While here, add more comments to it, as the script is getting more complex. So, better to add more things, to avoid accidentally breaking it while improving it. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/252cc849c79527ad496247e4c481961478adf41c.1586883286.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 113 ++++++++++++++++++++++++++++++--------------- 1 file changed, 75 insertions(+), 38 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 89b033285caf..d4dfe1e59989 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -2,7 +2,7 @@ # SPDX-License-Identifier: GPL-2.0-or-later use strict; -# Copyright (c) 2017-2019 Mauro Carvalho Chehab +# Copyright (c) 2017-2020 Mauro Carvalho Chehab # my $prefix = "./"; @@ -22,9 +22,12 @@ my $need = 0; my $optional = 0; my $need_symlink = 0; my $need_sphinx = 0; +my $need_venv = 0; +my $need_virtualenv = 0; my $rec_sphinx_upgrade = 0; my $install = ""; my $virtenv_dir = ""; +my $python_cmd = ""; my $min_version; # @@ -147,7 +150,7 @@ sub check_program($$) my $prog = shift; my $is_optional = shift; - return if findprog($prog); + return $prog if findprog($prog); add_package($prog, $is_optional); } @@ -168,9 +171,9 @@ sub check_python_module($$) my $prog = shift; my $is_optional = shift; - my $err = system("python3 -c 'import $prog' 2>/dev/null /dev/null"); - return if ($err == 0); - my $err = system("python -c 'import $prog' 2>/dev/null /dev/null"); + return if (!$python_cmd); + + my $err = system("$python_cmd -c 'import $prog' 2>/dev/null /dev/null"); return if ($err == 0); add_package($prog, $is_optional); @@ -225,16 +228,6 @@ sub get_sphinx_fname() return $fname; } - if ($virtualenv) { - my $prog = findprog("virtualenv-3"); - $prog = findprog("virtualenv-3.5") if (!$prog); - - check_program("virtualenv", 0) if (!$prog); - $need_sphinx = 1; - } else { - add_package("python-sphinx", 0); - } - return ""; } @@ -268,7 +261,10 @@ sub check_sphinx() $virtenv_dir = $virtenv_prefix . $rec_version; my $sphinx = get_sphinx_fname(); - return if ($sphinx eq ""); + if ($sphinx eq "") { + $need_sphinx = 1; + return; + } open IN, "$sphinx --version 2>&1 |" or die "$sphinx returned an error"; while () { @@ -336,6 +332,7 @@ sub give_debian_hints() my %map = ( "python-sphinx" => "python3-sphinx", "sphinx_rtd_theme" => "python3-sphinx-rtd-theme", + "ensurepip" => "python3-venv", "virtualenv" => "virtualenv", "dot" => "graphviz", "convert" => "imagemagick", @@ -672,13 +669,13 @@ sub check_distros() sub deactivate_help() { - printf "\tIf you want to exit the virtualenv, you can use:\n"; + printf "\nIf you want to exit the virtualenv, you can use:\n"; printf "\tdeactivate\n"; } sub check_needs() { - # Check for needed programs/tools + # Check if Sphinx is already accessible from current environment check_sphinx(); if ($system_release) { @@ -689,6 +686,43 @@ sub check_needs() print "To upgrade Sphinx, use:\n\n" if ($rec_sphinx_upgrade); + # Check python command line, trying first python3 + $python_cmd = findprog("python3"); + $python_cmd = check_program("python", 0) if (!$python_cmd); + + # Check the type of virtual env, depending on Python version + if ($python_cmd) { + if ($virtualenv) { + my $tmp = qx($python_cmd --version 2>&1); + if ($tmp =~ m/(\d+\.)(\d+\.)/) { + if ($1 >= 3 && $2 >= 3) { + $need_venv = 1; # python 3.3 or upper + } else { + $need_virtualenv = 1; + } + if ($1 < 3) { + # Complain if it finds python2 (or worse) + printf "Warning: python$1 support is deprecated. Use it with caution!\n"; + } + } else { + die "Warning: couldn't identify $python_cmd version!"; + } + } else { + add_package("python-sphinx", 0); + } + } + + # Set virtualenv command line, if python < 3.3 + my $virtualenv_cmd; + if ($need_virtualenv) { + $virtualenv_cmd = findprog("virtualenv-3"); + $virtualenv_cmd = findprog("virtualenv-3.5") if (!$virtualenv_cmd); + if (!$virtualenv_cmd) { + check_program("virtualenv", 0); + $virtualenv_cmd = "virtualenv"; + } + } + # Check for needed programs/tools check_perl_module("Pod::Usage", 0); check_program("make", 0); @@ -702,12 +736,30 @@ sub check_needs() check_program("rsvg-convert", 2) if ($pdf); check_program("latexmk", 2) if ($pdf); + if ($need_sphinx || $rec_sphinx_upgrade) { + check_python_module("ensurepip", 0) if ($need_venv); + } + + # Do distro-specific checks and output distro-install commands check_distros(); + if (!$python_cmd) { + if ($need == 1) { + die "Can't build as $need mandatory dependency is missing"; + } elsif ($need) { + die "Can't build as $need mandatory dependencies are missing"; + } + } + + # Check if sphinx-build is called sphinx-build-3 if ($need_symlink) { printf "\tsudo ln -sf %s /usr/bin/sphinx-build\n\n", which("sphinx-build-3"); } + + # NOTE: if the system has a too old Sphinx version installed, + # it will recommend installing a newer version using virtualenv + 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"; @@ -721,27 +773,12 @@ sub check_needs() exit (1); } else { my $rec_activate = "$virtenv_dir/bin/activate"; - my $virtualenv = findprog("virtualenv-3"); - my $rec_python3 = ""; - $virtualenv = findprog("virtualenv-3.5") if (!$virtualenv); - $virtualenv = findprog("virtualenv") if (!$virtualenv); - $virtualenv = "virtualenv" if (!$virtualenv); - - my $rel = ""; - if (index($system_release, "Ubuntu") != -1) { - $rel = $1 if ($system_release =~ /Ubuntu\s+(\d+)[.]/); - if ($rel && $rel >= 16) { - $rec_python3 = " -p python3"; - } - } - if (index($system_release, "Debian") != -1) { - $rel = $1 if ($system_release =~ /Debian\s+(\d+)/); - if ($rel && $rel >= 7) { - $rec_python3 = " -p python3"; - } - } - printf "\t$virtualenv$rec_python3 $virtenv_dir\n"; + if ($need_venv) { + printf "\t$python_cmd -m venv $virtenv_dir\n"; + } else { + printf "\t$virtualenv_cmd $virtenv_dir\n"; + } printf "\t. $rec_activate\n"; printf "\tpip install -r $requirement_file\n"; deactivate_help(); -- cgit v1.3 From 346282db9c6bc7ce2dad8ae640494f3f88d23889 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 14 Apr 2020 18:48:27 +0200 Subject: scripts: kernel-doc: proper handle @foo->bar() The pattern @foo->bar() is valid, as it can be used by a function pointer inside a struct passed as a parameter. Right now, it causes a warning: ./drivers/firewire/core-transaction.c:606: WARNING: Inline strong start-string without end-string. In this specific case, the kernel-doc markup is: /** * fw_core_remove_address_handler() - unregister an address handler * @handler: callback * * To be called in process context. * * When fw_core_remove_address_handler() returns, @handler->callback() is * guaranteed to not run on any CPU anymore. */ With seems valid on my eyes. So, instead of trying to hack the kernel-doc markup, let's teach it about how to handle such things. This should likely remove lots of other similar warnings as well. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/48b46426d7bf6ff7529f20e5718fbf4e9758e62c.1586881715.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 ++ 1 file changed, 2 insertions(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index f746ca8fa403..a9f6d4cea866 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -214,6 +214,7 @@ my $type_constant2 = '\%([-_\w]+)'; my $type_func = '(\w+)\(\)'; my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params +my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params my $type_env = '(\$\w+)'; my $type_enum = '\&(enum\s*([_\w]+))'; my $type_struct = '\&(struct\s*([_\w]+))'; @@ -249,6 +250,7 @@ my @highlights_rst = ( [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"], [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"], [$type_fp_param, "**\$1\\\\(\\\\)**"], + [$type_fp_param2, "**\$1\\\\(\\\\)**"], [$type_func, "\$1()"], [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"], [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"], -- cgit v1.3 From ee2aa7590398ecc0877552191e38d8a282f21cb8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 14 Apr 2020 18:48:28 +0200 Subject: scripts: kernel-doc: accept negation like !@var On a few places, it sometimes need to indicate a negation of a parameter, like: !@fshared This pattern happens, for example, at: kernel/futex.c and it is perfectly valid. However, kernel-doc currently transforms it into: !**fshared** This won't do what it would be expected. Fortunately, fixing the script is a simple matter of storing the "!" before "@" and adding it after the bold markup, like: **!fshared** Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/0314b47f8c3e1f9db00d5375a73dc3cddd8a21f2.1586881715.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index a9f6d4cea866..83b7260e44dc 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -213,6 +213,7 @@ my $type_constant = '\b``([^\`]+)``\b'; my $type_constant2 = '\%([-_\w]+)'; my $type_func = '(\w+)\(\)'; my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; +my $type_param_ref = '([\!]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params my $type_env = '(\$\w+)'; @@ -237,6 +238,7 @@ my @highlights_man = ( [$type_typedef, "\\\\fI\$1\\\\fP"], [$type_union, "\\\\fI\$1\\\\fP"], [$type_param, "\\\\fI\$1\\\\fP"], + [$type_param_ref, "\\\\fI\$1\$2\\\\fP"], [$type_member, "\\\\fI\$1\$2\$3\\\\fP"], [$type_fallback, "\\\\fI\$1\\\\fP"] ); @@ -258,7 +260,7 @@ my @highlights_rst = ( [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"], # in rst this can refer to any type [$type_fallback, "\\:c\\:type\\:`\$1`"], - [$type_param, "**\$1**"] + [$type_param_ref, "**\$1\$2**"] ); my $blankline_rst = "\n"; -- cgit v1.3 From 0d55d48b19ff3a31b295836da23223a52de7ef06 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 14 Apr 2020 18:48:29 +0200 Subject: scripts: kernel-doc: accept blank lines on parameter description Sphinx is very pedantic with respect to blank lines. Sometimes, in order to make it to properly handle something, we need to add a blank line. However, currently, any blank line inside a kernel-doc comment like: /* * @foo: bar * * foobar * * some description will be considered as if "foobar" was part of the description. This patch changes kernel-doc behavior. After it, foobar will be considered as part of the parameter text. The description will only be considered as such if it starts with: zero spaces after asterisk: *foo one space after asterisk: * foo or have a explicit Description section: * Description: Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/c07d2862792d75a2691d69c9eceb7b89a0164cc0.1586881715.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 35 +++++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 12 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 83b7260e44dc..f68d76dd97ba 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -331,13 +331,14 @@ my $lineprefix=""; # Parser states use constant { - STATE_NORMAL => 0, # normal code - STATE_NAME => 1, # looking for function name - STATE_BODY_MAYBE => 2, # body - or maybe more description - STATE_BODY => 3, # the body of the comment - STATE_PROTO => 4, # scanning prototype - STATE_DOCBLOCK => 5, # documentation block - STATE_INLINE => 6, # gathering documentation outside main block + STATE_NORMAL => 0, # normal code + STATE_NAME => 1, # looking for function name + STATE_BODY_MAYBE => 2, # body - or maybe more description + STATE_BODY => 3, # the body of the comment + STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line + STATE_PROTO => 5, # scanning prototype + STATE_DOCBLOCK => 6, # documentation block + STATE_INLINE => 7, # gathering doc outside main block }; my $state; my $in_doc_sect; @@ -1957,6 +1958,12 @@ sub process_body($$) { } } + if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) { + dump_section($file, $section, $contents); + $section = $section_default; + $contents = ""; + } + if (/$doc_sect/i) { # case insensitive for supported section names $newsection = $1; $newcontents = $2; @@ -2010,18 +2017,21 @@ sub process_body($$) { $state = STATE_PROTO; $brcount = 0; } elsif (/$doc_content/) { - # miguel-style comment kludge, look for blank lines after - # @parameter line to signify start of description if ($1 eq "") { - if ($section =~ m/^@/ || $section eq $section_context) { + if ($section eq $section_context) { dump_section($file, $section, $contents); $section = $section_default; $contents = ""; $new_start_line = $.; + $state = STATE_BODY; } else { + if ($section ne $section_default) { + $state = STATE_BODY_WITH_BLANK_LINE; + } else { + $state = STATE_BODY; + } $contents .= "\n"; } - $state = STATE_BODY; } elsif ($state == STATE_BODY_MAYBE) { # Continued declaration purpose chomp($declaration_purpose); @@ -2173,7 +2183,8 @@ sub process_file($) { process_normal(); } elsif ($state == STATE_NAME) { process_name($file, $_); - } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) { + } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE || + $state == STATE_BODY_WITH_BLANK_LINE) { process_body($file, $_); } elsif ($state == STATE_INLINE) { # scanning for inline parameters process_inline($file, $_); -- cgit v1.3 From a8b380c379efcade6008cb5e2359073b72e73ad8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 21 Apr 2020 16:31:05 +0200 Subject: scripts: sphinx-pre-install: only ask to activate valid venvs If a venv doesn't contain Sphinx, or has an older Sphinx version, ignore it. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/d11a00d88514e8a0357e1b0a05ebd518952a1d39.1587478901.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 53 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 37 insertions(+), 16 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index d4dfe1e59989..249edb3932af 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -231,6 +231,27 @@ sub get_sphinx_fname() return ""; } +sub get_sphinx_version($) +{ + my $cmd = shift; + my $ver; + + open IN, "$cmd --version 2>&1 |"; + while () { + if (m/^\s*sphinx-build\s+([\d\.]+)(\+\/[\da-f]+)?$/) { + $ver=$1; + last; + } + # Sphinx 1.2.x uses a different format + if (m/^\s*Sphinx.*\s+([\d\.]+)$/) { + $ver=$1; + last; + } + } + close IN; + return $ver; +} + sub check_sphinx() { my $rec_version; @@ -266,19 +287,8 @@ sub check_sphinx() return; } - open IN, "$sphinx --version 2>&1 |" or die "$sphinx returned an error"; - while () { - if (m/^\s*sphinx-build\s+([\d\.]+)(\+\/[\da-f]+)?$/) { - $cur_version=$1; - last; - } - # Sphinx 1.2.x uses a different format - if (m/^\s*Sphinx.*\s+([\d\.]+)$/) { - $cur_version=$1; - last; - } - } - close IN; + $cur_version = get_sphinx_version($sphinx); + die ("$sphinx returned an error") if (!$cur_version); die "$sphinx didn't return its version" if (!$cur_version); @@ -765,10 +775,21 @@ sub check_needs() my @activates = glob "$ENV{'PWD'}/${virtenv_prefix}*/bin/activate"; @activates = sort {$b cmp $a} @activates; + my ($activate, $ver); + foreach my $f (@activates) { + $activate = $f; + next if ($activate lt $min_activate); + + my $sphinx_cmd = $activate; + $sphinx_cmd =~ s/activate/sphinx-build/; + next if (! -f $sphinx_cmd); - 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"; + $ver = get_sphinx_version($sphinx_cmd); + last if ($ver ge $min_version); + } + if ($need_sphinx && ($activate ne "")) { + printf "\nNeed to activate Sphinx (version $ver) on virtualenv with:\n"; + printf "\t. $activate\n"; deactivate_help(); exit (1); } else { -- cgit v1.3 From 1ef70ced55976368275c468dfd436881d5580111 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 21 Apr 2020 16:31:06 +0200 Subject: scripts: sphinx-pre-install: change the warning for version < 2.4.4 As requested by Jon, change the version check, in order to not emit a warning if version is >= 1.7.9, but below 2.4.4. After this patch, if someone used an older version, it will say: ./scripts/sphinx-pre-install Sphinx version 1.7.9 Note: It is recommended at least Sphinx version 2.4.4 if you need PDF support. Detected OS: Fedora release 31 (Thirty One). To upgrade Sphinx, use: /devel/v4l/docs/sphinx_1.7.9/bin/python3 -m venv sphinx_2.4.4 . sphinx_2.4.4/bin/activate pip install -r ./Documentation/sphinx/requirements.txt If you want to exit the virtualenv, you can use: deactivate All optional dependencies are met. Needed package dependencies are met. If Sphinx is not detected at all, it Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/79584d317ba16f5d4f37801c5ee57cf04085f962.1587478901.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 249edb3932af..0d5684c08bbc 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -29,6 +29,8 @@ my $install = ""; my $virtenv_dir = ""; my $python_cmd = ""; my $min_version; +my $rec_version = "1.7.9"; # PDF won't build here +my $min_pdf_version = "2.4.4"; # Min version where pdf builds # # Command line arguments @@ -254,7 +256,7 @@ sub get_sphinx_version($) sub check_sphinx() { - my $rec_version; + my $default_version; my $cur_version; open IN, $conf or die "Can't open $conf"; @@ -271,15 +273,15 @@ sub check_sphinx() open IN, $requirement_file or die "Can't open $requirement_file"; while () { if (m/^\s*Sphinx\s*==\s*([\d\.]+)$/) { - $rec_version=$1; + $default_version=$1; last; } } close IN; - die "Can't get recommended sphinx version from $requirement_file" if (!$min_version); + die "Can't get default sphinx version from $requirement_file" if (!$default_version); - $virtenv_dir = $virtenv_prefix . $rec_version; + $virtenv_dir = $virtenv_prefix . $default_version; my $sphinx = get_sphinx_fname(); if ($sphinx eq "") { @@ -294,7 +296,7 @@ sub check_sphinx() if ($cur_version lt $min_version) { printf "ERROR: Sphinx version is %s. It should be >= %s (recommended >= %s)\n", - $cur_version, $min_version, $rec_version;; + $cur_version, $min_version, $default_version; $need_sphinx = 1; return; } @@ -302,6 +304,13 @@ sub check_sphinx() 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 " If you want pdf, you need at least $min_pdf_version.\n"; + $rec_sphinx_upgrade = 1; + return; + } + if ($cur_version lt $min_pdf_version) { + printf "Sphinx version %s\n", $cur_version; + print "Note: It is recommended at least Sphinx version $min_pdf_version if you need PDF support.\n"; $rec_sphinx_upgrade = 1; return; } -- cgit v1.3 From 2834a7412bb1a74722231d7198518f9456279156 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 21 Apr 2020 16:31:07 +0200 Subject: scripts: sphinx-pre-install: change recommendation text if venv exists If one is running a Sphinx version older than what's recommended, but there's already a newer working virtual env, change the text, as it is just a matter of switching to the new venv, instead of creating a new one from scratch. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/bcf79d0399a1c3444ca938dcdce599c3273980ab.1587478901.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 0d5684c08bbc..938b65d40fc8 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -29,6 +29,7 @@ my $install = ""; my $virtenv_dir = ""; my $python_cmd = ""; my $min_version; +my $cur_version; my $rec_version = "1.7.9"; # PDF won't build here my $min_pdf_version = "2.4.4"; # Min version where pdf builds @@ -257,7 +258,6 @@ sub get_sphinx_version($) sub check_sphinx() { my $default_version; - my $cur_version; open IN, $conf or die "Can't open $conf"; while () { @@ -703,8 +703,6 @@ sub check_needs() print "Unknown OS\n\n"; } - print "To upgrade Sphinx, use:\n\n" if ($rec_sphinx_upgrade); - # Check python command line, trying first python3 $python_cmd = findprog("python3"); $python_cmd = check_program("python", 0) if (!$python_cmd); @@ -786,24 +784,36 @@ sub check_needs() @activates = sort {$b cmp $a} @activates; my ($activate, $ver); foreach my $f (@activates) { - $activate = $f; - next if ($activate lt $min_activate); + next if ($f lt $min_activate); - my $sphinx_cmd = $activate; + my $sphinx_cmd = $f; $sphinx_cmd =~ s/activate/sphinx-build/; next if (! -f $sphinx_cmd); $ver = get_sphinx_version($sphinx_cmd); - last if ($ver ge $min_version); + if ($need_sphinx && ($ver ge $min_version)) { + $activate = $f; + last; + } elsif ($ver gt $cur_version) { + $activate = $f; + last; + } } - if ($need_sphinx && ($activate ne "")) { - printf "\nNeed to activate Sphinx (version $ver) on virtualenv with:\n"; - printf "\t. $activate\n"; - deactivate_help(); - exit (1); + if ($activate ne "") { + if ($need_sphinx) { + printf "\nNeed to activate Sphinx (version $ver) on virtualenv with:\n"; + printf "\t. $activate\n"; + deactivate_help(); + exit (1); + } else { + printf "\nYou may also use a newer Sphinx (version $ver) with:\n"; + printf "\tdeactivate && . $activate\n"; + } } else { my $rec_activate = "$virtenv_dir/bin/activate"; + print "To upgrade Sphinx, use:\n\n" if ($rec_sphinx_upgrade); + if ($need_venv) { printf "\t$python_cmd -m venv $virtenv_dir\n"; } else { -- cgit v1.3 From 412b09ddadd34e9be0d9a26e6de252361fafc237 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 21 Apr 2020 16:31:08 +0200 Subject: scripts: sphinx-pre-install: fix a bug when using with venv When python3 creates a venv, it adds python into it! This causes any upgrade recommendation to look like this: /devel/v4l/docs/sphinx_1.7.9/bin/python3 -m venv sphinx_2.4.4 . sphinx_2.4.4/bin/activate pip install -r ./Documentation/sphinx/requirements.txt With is wrong (and it may not work). So, when recomending an upgrade, exclude the venv dir from the search path, and get the system's python. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/aa622ff71bebf6960fc0262fb90e7ebc7a999a02.1587478901.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 938b65d40fc8..987aebf7e3a0 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -148,6 +148,24 @@ sub findprog($) } } +sub find_python_no_venv() +{ + my $prog = shift; + + my $cur_dir = qx(pwd); + $cur_dir =~ s/\s+$//; + + foreach my $dir (split(/:/, $ENV{PATH})) { + next if ($dir =~ m,($cur_dir)/sphinx,); + return "$dir/python3" if(-x "$dir/python3"); + } + foreach my $dir (split(/:/, $ENV{PATH})) { + next if ($dir =~ m,($cur_dir)/sphinx,); + return "$dir/python" if(-x "$dir/python"); + } + return "python"; +} + sub check_program($$) { my $prog = shift; @@ -814,6 +832,8 @@ sub check_needs() print "To upgrade Sphinx, use:\n\n" if ($rec_sphinx_upgrade); + $python_cmd = find_python_no_venv(); + if ($need_venv) { printf "\t$python_cmd -m venv $virtenv_dir\n"; } else { -- cgit v1.3 From ec43a27fffd025f718428d9f4f8df22fa765405f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 21 Apr 2020 18:27:58 +0200 Subject: scripts: sphinx-pre-install: change the output order When the script detects the need for an upgrade, it will print either a warning or a note. Let's change a little bit the order where messages will be displayed, in order to make easier for the user to identify the more important messages. It should now be like this: Detected OS: Fedora release 31 (Thirty One). Sphinx version: 1.7.9 Note: It is recommended at least Sphinx version 2.4.4 if you need PDF support. To upgrade Sphinx, use: /usr/bin/python3 -m venv sphinx_2.4.4 . sphinx_2.4.4/bin/activate pip install -r ./Documentation/sphinx/requirements.txt If you want to exit the virtualenv, you can use: deactivate All optional dependencies are met. Needed package dependencies are met. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/20200421182758.04e0a53e@coco.lan Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 987aebf7e3a0..c680c3efb176 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -320,15 +320,10 @@ sub check_sphinx() } 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 " If you want pdf, you need at least $min_pdf_version.\n"; $rec_sphinx_upgrade = 1; return; } if ($cur_version lt $min_pdf_version) { - printf "Sphinx version %s\n", $cur_version; - print "Note: It is recommended at least Sphinx version $min_pdf_version if you need PDF support.\n"; $rec_sphinx_upgrade = 1; return; } @@ -716,10 +711,11 @@ sub check_needs() check_sphinx(); if ($system_release) { - print "Detected OS: $system_release.\n\n"; + print "Detected OS: $system_release.\n"; } else { - print "Unknown OS\n\n"; + print "Unknown OS\n"; } + printf "Sphinx version: %s\n\n", $cur_version if ($cur_version); # Check python command line, trying first python3 $python_cmd = findprog("python3"); @@ -799,6 +795,13 @@ sub check_needs() my $min_activate = "$ENV{'PWD'}/${virtenv_prefix}${min_version}/bin/activate"; my @activates = glob "$ENV{'PWD'}/${virtenv_prefix}*/bin/activate"; + if ($cur_version lt $rec_version) { + print "Warning: It is recommended at least Sphinx version $rec_version.\n"; + print " If you want pdf, you need at least $min_pdf_version.\n"; + } + if ($cur_version lt $min_pdf_version) { + print "Note: It is recommended at least Sphinx version $min_pdf_version if you need PDF support.\n"; + } @activates = sort {$b cmp $a} @activates; my ($activate, $ver); foreach my $f (@activates) { -- cgit v1.3