From e86bdb24375a810ea7993d64ed406a803db71225 Mon Sep 17 00:00:00 2001 From: Aditya Srivastava Date: Fri, 14 May 2021 20:12:44 +0530 Subject: scripts: kernel-doc: reduce repeated regex expressions into variables There are some regex expressions in the kernel-doc script, which are used repeatedly in the script. Reduce such expressions into variables, which can be used everywhere. A quick manual check found that no errors and warnings were added/removed in this process. Suggested-by: Jonathan Corbet Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210514144244.25341-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 71 ++++++++++++++++++++++++++---------------------------- 1 file changed, 34 insertions(+), 37 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 4840e748fca8..7c4a6a507ac4 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -406,6 +406,8 @@ my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)'; my $doc_inline_end = '^\s*\*/\s*$'; my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$'; my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;'; +my $function_pointer = qr{([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)}; +my $attribute = qr{__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)}i; my %parameterdescs; my %parameterdesc_start_lines; @@ -694,7 +696,7 @@ sub output_function_man(%) { $post = ");"; } $type = $args{'parametertypes'}{$parameter}; - if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + if ($type =~ m/$function_pointer/) { # pointer-to-function print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n"; } else { @@ -974,7 +976,7 @@ sub output_function_rst(%) { $count++; $type = $args{'parametertypes'}{$parameter}; - if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + if ($type =~ m/$function_pointer/) { # pointer-to-function print $1 . $parameter . ") (" . $2 . ")"; } else { @@ -1211,7 +1213,9 @@ sub dump_struct($$) { my $members; my $type = qr{struct|union}; # For capturing struct/union definition body, i.e. "{members*}qualifiers*" - my $definition_body = qr{\{(.*)\}(?:\s*(?:__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*}; + my $qualifiers = qr{$attribute|__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned}; + my $definition_body = qr{\{(.*)\}\s*$qualifiers*}; + my $struct_members = qr{($type)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;}; if ($x =~ /($type)\s+(\w+)\s*$definition_body/) { $decl_type = $1; @@ -1235,27 +1239,27 @@ sub dump_struct($$) { # strip comments: $members =~ s/\/\*.*?\*\///gos; # strip attributes - $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi; + $members =~ s/\s*$attribute/ /gi; $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos; $members =~ s/\s*__packed\s*/ /gos; $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos; $members =~ s/\s*____cacheline_aligned_in_smp/ /gos; $members =~ s/\s*____cacheline_aligned/ /gos; + my $args = qr{([^,)]+)}; # replace DECLARE_BITMAP $members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos; - $members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos; + $members =~ s/DECLARE_BITMAP\s*\($args,\s*$args\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos; # replace DECLARE_HASHTABLE - $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos; + $members =~ s/DECLARE_HASHTABLE\s*\($args,\s*$args\)/unsigned long $1\[1 << (($2) - 1)\]/gos; # replace DECLARE_KFIFO - $members =~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos; + $members =~ s/DECLARE_KFIFO\s*\($args,\s*$args,\s*$args\)/$2 \*$1/gos; # replace DECLARE_KFIFO_PTR - $members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos; - + $members =~ s/DECLARE_KFIFO_PTR\s*\($args,\s*$args\)/$2 \*$1/gos; my $declaration = $members; # Split nested struct/union elements as newer ones - while ($members =~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/) { + while ($members =~ m/$struct_members/) { my $newmember; my $maintype = $1; my $ids = $4; @@ -1315,7 +1319,7 @@ sub dump_struct($$) { } } } - $members =~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/$newmember/; + $members =~ s/$struct_members/$newmember/; } # Ignore other nested elements, like enums @@ -1555,8 +1559,9 @@ sub create_parameterlist($$$$) { my $param; # temporarily replace commas inside function pointer definition - while ($args =~ /(\([^\),]+),/) { - $args =~ s/(\([^\),]+),/$1#/g; + my $arg_expr = qr{\([^\),]+}; + while ($args =~ /$arg_expr,/) { + $args =~ s/($arg_expr),/$1#/g; } foreach my $arg (split($splitter, $args)) { @@ -1707,7 +1712,7 @@ sub check_sections($$$$$) { foreach $px (0 .. $#prms) { $prm_clean = $prms[$px]; $prm_clean =~ s/\[.*\]//; - $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i; + $prm_clean =~ s/$attribute//i; # ignore array size in a parameter string; # however, the original param string may contain # spaces, e.g.: addr[6 + 2] @@ -1809,8 +1814,14 @@ sub dump_function($$) { # - parport_register_device (function pointer parameters) # - atomic_set (macro) # - pci_match_device, __copy_to_user (long return type) - - if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) { + my $name = qr{[a-zA-Z0-9_~:]+}; + my $prototype_end1 = qr{[^\(]*}; + my $prototype_end2 = qr{[^\{]*}; + my $prototype_end = qr{\(($prototype_end1|$prototype_end2)\)}; + my $type1 = qr{[\w\s]+}; + my $type2 = qr{$type1\*+}; + + if ($define && $prototype =~ m/^()($name)\s+/) { # This is an object-like macro, it has no return type and no parameter # list. # Function-like macros are not allowed to have spaces between @@ -1818,23 +1829,9 @@ sub dump_function($$) { $return_type = $1; $declaration_name = $2; $noret = 1; - } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || - $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || - $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || - $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || - $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) { + } elsif ($prototype =~ m/^()($name)\s*$prototype_end/ || + $prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ || + $prototype =~ m/^($type2+)\s*($name)\s*$prototype_end/) { $return_type = $1; $declaration_name = $2; my $args = $3; @@ -2111,12 +2108,12 @@ sub process_name($$) { } elsif (/$doc_decl/o) { $identifier = $1; my $is_kernel_comment = 0; - my $decl_start = qr{\s*\*}; + my $decl_start = qr{$doc_com}; # test for pointer declaration type, foo * bar() - desc my $fn_type = qr{\w+\s*\*\s*}; my $parenthesis = qr{\(\w*\)}; my $decl_end = qr{[-:].*}; - if (/^$decl_start\s*([\w\s]+?)$parenthesis?\s*$decl_end?$/) { + if (/^$decl_start([\w\s]+?)$parenthesis?\s*$decl_end?$/) { $identifier = $1; } if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) { @@ -2126,8 +2123,8 @@ sub process_name($$) { } # Look for foo() or static void foo() - description; or misspelt # identifier - elsif (/^$decl_start\s*$fn_type?(\w+)\s*$parenthesis?\s*$decl_end?$/ || - /^$decl_start\s*$fn_type?(\w+.*)$parenthesis?\s*$decl_end$/) { + elsif (/^$decl_start$fn_type?(\w+)\s*$parenthesis?\s*$decl_end?$/ || + /^$decl_start$fn_type?(\w+.*)$parenthesis?\s*$decl_end$/) { $identifier = $1; $decl_type = 'function'; $identifier =~ s/^define\s+//; -- cgit v1.2.3 From e50899122f3204946bb3559da23700c2e5b9568b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 25 May 2021 15:27:27 +0200 Subject: scripts: sphinx-pre-install: rework the sphinx install logic The sphinx-pre-install supports installing sphinx via a virtual environment using pip/pypi or directly from the distribution's package, when --no-virtualenv is used. However, even when --no-virtualenv, the current logic is still recomending to install a virtual env, due to a regression. It turns that the logic there is complex, as it depends on several different conditions. Split the code which recommends Sphinx on two separate functions, in order to clean up the code. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/9dedaec201803017b7a7dc24a074f3a4f040b72a.1621949137.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 208 ++++++++++++++++++++++++++++++--------------- 1 file changed, 140 insertions(+), 68 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index fe92020d67e3..b5fec149f473 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -24,7 +24,6 @@ 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 = ""; @@ -33,6 +32,7 @@ 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 + # # Command line arguments # @@ -319,10 +319,7 @@ sub check_sphinx() return; } - if ($cur_version lt $rec_version) { - $rec_sphinx_upgrade = 1; - return; - } + return if ($cur_version lt $rec_version); # On version check mode, just assume Sphinx has all mandatory deps exit (0) if ($version_check); @@ -701,6 +698,141 @@ sub deactivate_help() printf "\tdeactivate\n"; } +sub get_virtenv() +{ + my $min_activate = "$ENV{'PWD'}/${virtenv_prefix}${min_version}/bin/activate"; + my @activates = glob "$ENV{'PWD'}/${virtenv_prefix}*/bin/activate"; + + @activates = sort {$b cmp $a} @activates; + my ($activate, $ver); + foreach my $f (@activates) { + next if ($f lt $min_activate); + + my $sphinx_cmd = $f; + $sphinx_cmd =~ s/activate/sphinx-build/; + next if (! -f $sphinx_cmd); + + my $ver = get_sphinx_version($sphinx_cmd); + if ($need_sphinx && ($ver ge $min_version)) { + return ($f, $ver); + } elsif ($ver gt $cur_version) { + return ($f, $ver); + } + } + return ("", ""); +} + +# +# The logic here is complex, as it have to deal with different versions: +# - minimal supported version; +# - minimal PDF version; +# - recommended version. +# It also needs to work fine with both distro's package and venv/virtualenv +sub recommend_sphinx_version($) +{ + my $virtualenv_cmd = shift; + + # Avoid running sphinx-builds from venv if $cur_version is good + return if ($cur_version && ($cur_version ge $rec_version)); + + my $latest_avail_ver; + my $rec_sphinx_upgrade = 0; + + # Get the highest version from sphinx_*/bin/sphinx-build and the + # corresponding command to activate the venv/virtenv + my ($activate, $venv_ver) = get_virtenv(); + + if (($activate ne "") && ($venv_ver gt $cur_version)) { + $latest_avail_ver = $venv_ver; + } else { + $latest_avail_ver = $cur_version if ($cur_version); + } + + if (!$need_sphinx) { + # sphinx-build is present and its version is >= $min_version + + #only recommend enabling a newer virtenv version if makes sense. + if ($latest_avail_ver gt $cur_version) { + printf "\nYou may also use the newer Sphinx version $venv_ver with:\n"; + printf "\tdeactivate\n" if ($ENV{'PWD'} =~ /${virtenv_prefix}/); + printf "\t. $activate\n"; + deactivate_help(); + + return; + } + return if ($latest_avail_ver ge $rec_version); + } + + if (!$virtualenv) { + # No sphinx either via package or via virtenv. As we can't + # Compare the versions here, just return, recommending the + # user to install it from the package distro. + return if (!$latest_avail_ver); + + # User doesn't want a virtenv recommendation, but he already + # installed one via virtenv with a newer version. + # So, print commands to enable it + if ($latest_avail_ver gt $cur_version) { + printf "\nYou may also use the Sphinx virtualenv version $venv_ver with:\n"; + printf "\tdeactivate\n" if ($ENV{'PWD'} =~ /${virtenv_prefix}/); + printf "\t. $activate\n"; + deactivate_help(); + + return; + } + print "\n"; + } else { + $need++ if ($need_sphinx); + } + + # Suggest newer versions if current ones are too old + if ($latest_avail_ver && $cur_version ge $min_version) { + # If there's a good enough version, ask the user to enable it + if ($latest_avail_ver ge $rec_version) { + printf "\nNeed to activate Sphinx (version $venv_ver) on virtualenv with:\n"; + printf "\t. $activate\n"; + deactivate_help(); + + return; + } + + # Version is above the minimal required one, but may be + # below the recommended one. So, print warnings/notes + + if ($latest_avail_ver lt $rec_version) { + print "Warning: It is recommended at least Sphinx version $rec_version.\n"; + $rec_sphinx_upgrade = 1; + } + if ($latest_avail_ver lt $min_pdf_version) { + print "note: If you want pdf, you need at least $min_pdf_version.\n"; + } + } + + # At this point, either it needs Sphinx or upgrade is recommended, + # both via pip + + if ($rec_sphinx_upgrade) { + if (!$virtualenv) { + print "Instead of install/upgrade Python Sphinx pkg, you could use pip/pypi with:\n\n"; + } else { + print "To upgrade Sphinx, use:\n\n"; + } + } else { + print "Sphinx needs to be installed either as a package or via pip/pypi with:\n"; + } + + $python_cmd = find_python_no_venv(); + + if ($need_venv) { + printf "\t$python_cmd -m venv $virtenv_dir\n"; + } else { + printf "\t$virtualenv_cmd $virtenv_dir\n"; + } + printf "\t. $virtenv_dir/bin/activate\n"; + printf "\tpip install -r $requirement_file\n"; + deactivate_help(); +} + sub check_needs() { # Check if Sphinx is already accessible from current environment @@ -763,8 +895,8 @@ 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); + if ($need_venv) { + check_python_module("ensurepip", 0); } # Do distro-specific checks and output distro-install commands @@ -784,67 +916,7 @@ sub check_needs() 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"; - - 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) { - next if ($f lt $min_activate); - - my $sphinx_cmd = $f; - $sphinx_cmd =~ s/activate/sphinx-build/; - next if (! -f $sphinx_cmd); - - $ver = get_sphinx_version($sphinx_cmd); - if ($need_sphinx && ($ver ge $min_version)) { - $activate = $f; - last; - } elsif ($ver gt $cur_version) { - $activate = $f; - last; - } - } - 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); - - $python_cmd = find_python_no_venv(); - - 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(); - - $need++ if (!$rec_sphinx_upgrade); - } - } + recommend_sphinx_version($virtualenv_cmd); printf "\n"; print "All optional dependencies are met.\n" if (!$optional); -- cgit v1.2.3 From a5f785f1021857a889b1f5b7cc1d83efd4404336 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 25 May 2021 15:27:28 +0200 Subject: scripts: sphinx-pre-install: fix the need of virtenv packages The pip packages are only needed when the distro-provided Sphinx version is not good enough. Don't recommend installing it if not needed. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/04ce53b77b37f1e495c3abc39c2d3dc407895dc0.1621949137.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 122 +++++++++++++++++++++++++++------------------ 1 file changed, 74 insertions(+), 48 deletions(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index b5fec149f473..288e86a9d1e5 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -22,16 +22,18 @@ my $need = 0; my $optional = 0; my $need_symlink = 0; my $need_sphinx = 0; -my $need_venv = 0; +my $need_pip = 0; my $need_virtualenv = 0; +my $rec_sphinx_upgrade = 0; my $install = ""; my $virtenv_dir = ""; my $python_cmd = ""; +my $activate_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 - +my $latest_avail_ver; # # Command line arguments @@ -700,11 +702,12 @@ sub deactivate_help() sub get_virtenv() { + my $ver; my $min_activate = "$ENV{'PWD'}/${virtenv_prefix}${min_version}/bin/activate"; my @activates = glob "$ENV{'PWD'}/${virtenv_prefix}*/bin/activate"; @activates = sort {$b cmp $a} @activates; - my ($activate, $ver); + foreach my $f (@activates) { next if ($f lt $min_activate); @@ -722,40 +725,67 @@ sub get_virtenv() return ("", ""); } -# -# The logic here is complex, as it have to deal with different versions: -# - minimal supported version; -# - minimal PDF version; -# - recommended version. -# It also needs to work fine with both distro's package and venv/virtualenv -sub recommend_sphinx_version($) +sub recommend_sphinx_upgrade() { - my $virtualenv_cmd = shift; + my $venv_ver; # Avoid running sphinx-builds from venv if $cur_version is good - return if ($cur_version && ($cur_version ge $rec_version)); - - my $latest_avail_ver; - my $rec_sphinx_upgrade = 0; + if ($cur_version && ($cur_version ge $rec_version)) { + $latest_avail_ver = $cur_version; + return; + } # Get the highest version from sphinx_*/bin/sphinx-build and the # corresponding command to activate the venv/virtenv - my ($activate, $venv_ver) = get_virtenv(); + $activate_cmd = get_virtenv(); - if (($activate ne "") && ($venv_ver gt $cur_version)) { + # Store the highest version from Sphinx existing virtualenvs + if (($activate_cmd ne "") && ($venv_ver gt $cur_version)) { $latest_avail_ver = $venv_ver; } else { $latest_avail_ver = $cur_version if ($cur_version); } + # As we don't know package version of Sphinx, and there's no + # virtual environments, don't check if upgrades are needed + if (!$virtualenv) { + return if (!$latest_avail_ver); + } + + # Either there are already a virtual env or a new one should be created + $need_pip = 1; + + # Return if the reason is due to an upgrade or not + if ($latest_avail_ver lt $rec_version) { + $rec_sphinx_upgrade = 1; + } +} + +# +# The logic here is complex, as it have to deal with different versions: +# - minimal supported version; +# - minimal PDF version; +# - recommended version. +# It also needs to work fine with both distro's package and venv/virtualenv +sub recommend_sphinx_version($) +{ + my $virtualenv_cmd = shift; + + if ($latest_avail_ver lt $min_pdf_version) { + print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n"; + } + + # Version is OK. Nothing to do. + return if ($cur_version && ($cur_version ge $rec_version)); + if (!$need_sphinx) { # sphinx-build is present and its version is >= $min_version #only recommend enabling a newer virtenv version if makes sense. if ($latest_avail_ver gt $cur_version) { - printf "\nYou may also use the newer Sphinx version $venv_ver with:\n"; + printf "\nYou may also use the newer Sphinx version $latest_avail_ver with:\n"; printf "\tdeactivate\n" if ($ENV{'PWD'} =~ /${virtenv_prefix}/); - printf "\t. $activate\n"; + printf "\t. $activate_cmd\n"; deactivate_help(); return; @@ -773,9 +803,9 @@ sub recommend_sphinx_version($) # installed one via virtenv with a newer version. # So, print commands to enable it if ($latest_avail_ver gt $cur_version) { - printf "\nYou may also use the Sphinx virtualenv version $venv_ver with:\n"; + printf "\nYou may also use the Sphinx virtualenv version $latest_avail_ver with:\n"; printf "\tdeactivate\n" if ($ENV{'PWD'} =~ /${virtenv_prefix}/); - printf "\t. $activate\n"; + printf "\t. $activate_cmd\n"; deactivate_help(); return; @@ -789,8 +819,8 @@ sub recommend_sphinx_version($) if ($latest_avail_ver && $cur_version ge $min_version) { # If there's a good enough version, ask the user to enable it if ($latest_avail_ver ge $rec_version) { - printf "\nNeed to activate Sphinx (version $venv_ver) on virtualenv with:\n"; - printf "\t. $activate\n"; + printf "\nNeed to activate Sphinx (version $latest_avail_ver) on virtualenv with:\n"; + printf "\t. $activate_cmd\n"; deactivate_help(); return; @@ -801,10 +831,6 @@ sub recommend_sphinx_version($) if ($latest_avail_ver lt $rec_version) { print "Warning: It is recommended at least Sphinx version $rec_version.\n"; - $rec_sphinx_upgrade = 1; - } - if ($latest_avail_ver lt $min_pdf_version) { - print "note: If you want pdf, you need at least $min_pdf_version.\n"; } } @@ -823,11 +849,8 @@ sub recommend_sphinx_version($) $python_cmd = find_python_no_venv(); - if ($need_venv) { - printf "\t$python_cmd -m venv $virtenv_dir\n"; - } else { - printf "\t$virtualenv_cmd $virtenv_dir\n"; - } + printf "\t$virtualenv_cmd $virtenv_dir\n"; + printf "\t. $virtenv_dir/bin/activate\n"; printf "\tpip install -r $requirement_file\n"; deactivate_help(); @@ -854,15 +877,14 @@ sub check_needs() 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) { # Fail if it finds python2 (or worse) die "Python 3 is required to build the kernel docs\n"; } + if ($1 == 3 && $2 < 3) { + # Need Python 3.3 or upper for venv + $need_virtualenv = 1; + } } else { die "Warning: couldn't identify $python_cmd version!"; } @@ -871,14 +893,22 @@ sub check_needs() } } - # Set virtualenv command line, if python < 3.3 + recommend_sphinx_upgrade(); + 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"; + + if ($need_pip) { + # Set virtualenv command line, if python < 3.3 + 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"; + } + } else { + $virtualenv_cmd = "$python_cmd -m venv"; + check_python_module("ensurepip", 0); } } @@ -895,10 +925,6 @@ sub check_needs() check_program("rsvg-convert", 2) if ($pdf); check_program("latexmk", 2) if ($pdf); - if ($need_venv) { - check_python_module("ensurepip", 0); - } - # Do distro-specific checks and output distro-install commands check_distros(); -- cgit v1.2.3 From 709dedfdf3daa8719240ecff1c0b70b278005386 Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Wed, 2 Jun 2021 20:28:06 -0500 Subject: documentation-file-ref-check: Make git check work for multiple working directories With multiple git working directories, '.git' may also be a text file linking to the actual git tree instead of a directory. Cc: Mauro Carvalho Chehab Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Rob Herring Reviewed-by: Mauro Carvalho Chehab Tested-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/20210603012806.331132-1-robh@kernel.org Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index c71832b2312b..7187ea5e5149 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -24,7 +24,7 @@ my $help = 0; my $fix = 0; my $warn = 0; -if (! -d ".git") { +if (! -e ".git") { printf "Warning: can't check if file exists, as this is not a git tree\n"; exit 0; } -- cgit v1.2.3