From 9e78e7fc0b20bcc0d5599f71d297b6fa1a2e7c5f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 29 May 2019 20:09:27 -0300 Subject: scripts/documentation-file-ref-check: better handle translations Only seek for translation renames inside the translation directory. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'scripts/documentation-file-ref-check') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index 63e9542656f1..6b622b88f4cf 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -141,6 +141,10 @@ print "Auto-fixing broken references. Please double-check the results\n"; foreach my $ref (keys %broken_ref) { my $new =$ref; + my $basedir = "."; + # On translations, only seek inside the translations directory + $basedir = $1 if ($ref =~ m,(Documentation/translations/[^/]+),); + # get just the basename $new =~ s,.*/,,; @@ -161,18 +165,18 @@ foreach my $ref (keys %broken_ref) { # usual reason for breakage: file renamed to .rst if (!$f) { $new =~ s/\.txt$/.rst/; - $f=qx(find . -iname $new) if ($new); + $f=qx(find $basedir -iname $new) if ($new); } # usual reason for breakage: use dash or underline if (!$f) { $new =~ s/[-_]/[-_]/g; - $f=qx(find . -iname $new) if ($new); + $f=qx(find $basedir -iname $new) if ($new); } # Wild guess: seek for the same name on another place if (!$f) { - $f = qx(find . -iname $new) if ($new); + $f = qx(find $basedir -iname $new) if ($new); } my @find = split /\s+/, $f; -- cgit From aeaacbfed853c17b8ac5e73c21f54d7f0805d899 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 29 May 2019 20:09:28 -0300 Subject: scripts/documentation-file-ref-check: exclude false-positives There are at least two cases where a documentation file was gone for good, but the text still mentions it: 1) drivers/vhost/vhost.c: the reference for Documentation/virtual/lguest/lguest.c is just to give credits to the original work that vhost replaced; 2) Documentation/scsi/scsi_mid_low_api.txt: It gives credit and mentions the old Documentation/Configure.help file that used to be part of Kernel 2.4.x As we don't want to keep the script to keep pinpoint to those every time, let's add a logic at the script to allow it to ignore valid false-positives like the above. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'scripts/documentation-file-ref-check') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index 6b622b88f4cf..05235775cc71 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -8,6 +8,14 @@ use warnings; use strict; use Getopt::Long qw(:config no_auto_abbrev); +# NOTE: only add things here when the file was gone, but the text wants +# to mention a past documentation file, for example, to give credits for +# the original work. +my %false_positives = ( + "Documentation/scsi/scsi_mid_low_api.txt" => "Documentation/Configure.help", + "drivers/vhost/vhost.c" => "Documentation/virtual/lguest/lguest.c", +); + my $scriptname = $0; $scriptname =~ s,.*/([^/]+/),$1,; @@ -122,6 +130,11 @@ while () { next if (grep -e, glob("$path/$ref $path/$fulref")); } + # Discard known false-positives + if (defined($false_positives{$f})) { + next if ($false_positives{$f} eq $fulref); + } + if ($fix) { if (!($ref =~ m/(scripts|Kconfig|Kbuild)/)) { $broken_ref{$ref}++; -- cgit From 4904aeed9f686c90dba72980f0067ac1a7dbbfb6 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 29 May 2019 20:09:29 -0300 Subject: scripts/documentation-file-ref-check: improve tools ref handling There's a false positive on perf/util: tools/perf/util/s390-cpumsf.c: Documentation/perf.data-file-format.txt The file is there at tools/perf/Documentation/, but the logic with detects relative documentation references inside tools is not capable of detecting it. So, improve it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts/documentation-file-ref-check') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index 05235775cc71..5d775ca7469b 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -127,7 +127,7 @@ while () { if ($f =~ m/tools/) { my $path = $f; $path =~ s,(.*)/.*,$1,; - next if (grep -e, glob("$path/$ref $path/$fulref")); + next if (grep -e, glob("$path/$ref $path/../$ref $path/$fulref")); } # Discard known false-positives -- cgit From 0ca862e6f1c7e58e4eb9758fdb09255e6104d6a0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 29 May 2019 20:09:30 -0300 Subject: scripts/documentation-file-ref-check: teach about .txt -> .yaml renames At DT, files are being renamed to jason. Teach the script how to handle such renames when used in fix mode. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) (limited to 'scripts/documentation-file-ref-check') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index 5d775ca7469b..ff16db269079 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -165,13 +165,22 @@ foreach my $ref (keys %broken_ref) { # usual reason for breakage: DT file moved around if ($ref =~ /devicetree/) { - my $search = $new; - $search =~ s,^.*/,,; - $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search); + # usual reason for breakage: DT file renamed to .yaml if (!$f) { - # Manufacturer name may have changed - $search =~ s/^.*,//; + my $new_ref = $ref; + $new_ref =~ s/\.txt$/.yaml/; + $f=$new_ref if (-f $new_ref); + } + + if (!$f) { + my $search = $new; + $search =~ s,^.*/,,; $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search); + if (!$f) { + # Manufacturer name may have changed + $search =~ s/^.*,//; + $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search); + } } } -- cgit From b1663d7e3a7961fc45262fd68a89253f2803036c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 4 Jun 2019 09:26:27 -0300 Subject: docs: Kbuild/Makefile: allow check for missing docs at build time While this doesn't make sense for production Kernels, in order to avoid regressions when documents are touched, let's add a check target at the make file. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'scripts/documentation-file-ref-check') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index ff16db269079..440227bb55a9 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -22,9 +22,16 @@ $scriptname =~ s,.*/([^/]+/),$1,; # Parse arguments my $help = 0; my $fix = 0; +my $warn = 0; + +if (! -d ".git") { + printf "Warning: can't check if file exists, as this is not a git tree"; + exit 0; +} GetOptions( 'fix' => \$fix, + 'warn' => \$warn, 'h|help|usage' => \$help, ); @@ -139,6 +146,8 @@ while () { if (!($ref =~ m/(scripts|Kconfig|Kbuild)/)) { $broken_ref{$ref}++; } + } elsif ($warn) { + print STDERR "Warning: $f references a file that doesn't exist: $fulref\n"; } else { print STDERR "$f: $fulref\n"; } -- cgit From 4ca9bc225e46eb7bc040dd948be7cb68975d80d3 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 12 Jun 2019 14:52:59 -0300 Subject: docs: target: convert docs to ReST and rename to *.rst Convert the TCM docs to ReST format and add them to the bookset. This has a mix of userspace-faced and Kernelspace faced docs. Still, it sounds a better candidate to be added at the kernel API set of docs. The conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts/documentation-file-ref-check') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index 440227bb55a9..a4139a576726 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -124,7 +124,7 @@ while () { # Remove sched-pelt false-positive next if ($fulref =~ m,^Documentation/scheduler/sched-pelt$,); - # Discard some build examples from Documentation/target/tcm_mod_builder.txt + # Discard some build examples from Documentation/target/tcm_mod_builder.rst next if ($fulref =~ m,mnt/sdb/lio-core-2.6.git/Documentation/target,); # Check if exists, evaluating wildcards -- cgit From 407b584d155be67a9311a62da8d7874f62b987ac Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 13 Jun 2019 07:29:17 -0300 Subject: scripts/documentation-file-ref-check: ignore output dir When there's no Documentation/output directory, the script will complain about those missing references: Documentation/doc-guide/sphinx.rst: Documentation/output Documentation/doc-guide/sphinx.rst: Documentation/output Documentation/process/howto.rst: Documentation/output Documentation/translations/it_IT/doc-guide/sphinx.rst: Documentation/output Documentation/translations/it_IT/doc-guide/sphinx.rst: Documentation/output Documentation/translations/it_IT/process/howto.rst: Documentation/output Documentation/translations/ja_JP/howto.rst: Documentation/output Documentation/translations/ko_KR/howto.rst: Documentation/output Those are false positives, so add an ignore rule for them. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 3 +++ 1 file changed, 3 insertions(+) (limited to 'scripts/documentation-file-ref-check') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check index a4139a576726..7784c54aa38b 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -90,6 +90,9 @@ while () { # Skip this script next if ($f eq $scriptname); + # Ignore the dir where documentation will be built + next if ($ln =~ m,\b(\S*)Documentation/output,); + if ($ln =~ m,\b(\S*)(Documentation/[A-Za-z0-9\_\.\,\~/\*\[\]\?+-]*)(.*),) { my $prefix = $1; my $ref = $2; -- cgit