~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/scripts/documentation-file-ref-check

Version: ~ [ linux-6.11.5 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.58 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.114 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.169 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.228 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.284 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.322 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.9 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

  1 #!/usr/bin/env perl
  2 # SPDX-License-Identifier: GPL-2.0
  3 #
  4 # Treewide grep for references to files under Documentation, and report
  5 # non-existing files in stderr.
  6 
  7 use warnings;
  8 use strict;
  9 use Getopt::Long qw(:config no_auto_abbrev);
 10 
 11 # NOTE: only add things here when the file was gone, but the text wants
 12 # to mention a past documentation file, for example, to give credits for
 13 # the original work.
 14 my %false_positives = (
 15         "Documentation/scsi/scsi_mid_low_api.rst" => "Documentation/Configure.help",
 16         "drivers/vhost/vhost.c" => "Documentation/virtual/lguest/lguest.c",
 17 );
 18 
 19 my $scriptname = $0;
 20 $scriptname =~ s,.*/([^/]+/),$1,;
 21 
 22 # Parse arguments
 23 my $help = 0;
 24 my $fix = 0;
 25 my $warn = 0;
 26 
 27 if (! -e ".git") {
 28         printf "Warning: can't check if file exists, as this is not a git tree\n";
 29         exit 0;
 30 }
 31 
 32 GetOptions(
 33         'fix' => \$fix,
 34         'warn' => \$warn,
 35         'h|help|usage' => \$help,
 36 );
 37 
 38 if ($help != 0) {
 39     print "$scriptname [--help] [--fix]\n";
 40     exit -1;
 41 }
 42 
 43 # Step 1: find broken references
 44 print "Finding broken references. This may take a while...  " if ($fix);
 45 
 46 my %broken_ref;
 47 
 48 my $doc_fix = 0;
 49 
 50 open IN, "git grep ':doc:\`' Documentation/|"
 51      or die "Failed to run git grep";
 52 while (<IN>) {
 53         next if (!m,^([^:]+):.*\:doc\:\`([^\`]+)\`,);
 54         next if (m,sphinx/,);
 55 
 56         my $file = $1;
 57         my $d = $1;
 58         my $doc_ref = $2;
 59 
 60         my $f = $doc_ref;
 61 
 62         $d =~ s,(.*/).*,$1,;
 63         $f =~ s,.*\<([^\>]+)\>,$1,;
 64 
 65         if ($f =~ m,^/,) {
 66                 $f = "$f.rst";
 67                 $f =~ s,^/,Documentation/,;
 68         } else {
 69                 $f = "$d$f.rst";
 70         }
 71 
 72         next if (grep -e, glob("$f"));
 73 
 74         if ($fix && !$doc_fix) {
 75                 print STDERR "\nWARNING: Currently, can't fix broken :doc:`` fields\n";
 76         }
 77         $doc_fix++;
 78 
 79         print STDERR "$file: :doc:`$doc_ref`\n";
 80 }
 81 close IN;
 82 
 83 open IN, "git grep 'Documentation/'|"
 84      or die "Failed to run git grep";
 85 while (<IN>) {
 86         next if (!m/^([^:]+):(.*)/);
 87 
 88         my $f = $1;
 89         my $ln = $2;
 90 
 91         # On linux-next, discard the Next/ directory
 92         next if ($f =~ m,^Next/,);
 93 
 94         # Makefiles and scripts contain nasty expressions to parse docs
 95         next if ($f =~ m/Makefile/ || $f =~ m/\.sh$/);
 96 
 97         # It doesn't make sense to parse hidden files
 98         next if ($f =~ m#/\.#);
 99 
100         # Skip this script
101         next if ($f eq $scriptname);
102 
103         # Ignore the dir where documentation will be built
104         next if ($ln =~ m,\b(\S*)Documentation/output,);
105 
106         if ($ln =~ m,\b(\S*)(Documentation/[A-Za-z0-9\_\.\,\~/\*\[\]\?+-]*)(.*),) {
107                 my $prefix = $1;
108                 my $ref = $2;
109                 my $base = $2;
110                 my $extra = $3;
111 
112                 # some file references are like:
113                 # /usr/src/linux/Documentation/DMA-{API,mapping}.txt
114                 # For now, ignore them
115                 next if ($extra =~ m/^{/);
116 
117                 # Remove footnotes at the end like:
118                 # Documentation/devicetree/dt-object-internal.txt[1]
119                 $ref =~ s/(txt|rst)\[\d+]$/$1/;
120 
121                 # Remove ending ']' without any '['
122                 $ref =~ s/\].*// if (!($ref =~ m/\[/));
123 
124                 # Remove puntuation marks at the end
125                 $ref =~ s/[\,\.]+$//;
126 
127                 my $fulref = "$prefix$ref";
128 
129                 $fulref =~ s/^(\<file|ref)://;
130                 $fulref =~ s/^[\'\`]+//;
131                 $fulref =~ s,^\$\(.*\)/,,;
132                 $base =~ s,.*/,,;
133 
134                 # Remove URL false-positives
135                 next if ($fulref =~ m/^http/);
136 
137                 # Remove sched-pelt false-positive
138                 next if ($fulref =~ m,^Documentation/scheduler/sched-pelt$,);
139 
140                 # Discard some build examples from Documentation/target/tcm_mod_builder.rst
141                 next if ($fulref =~ m,mnt/sdb/lio-core-2.6.git/Documentation/target,);
142 
143                 # Check if exists, evaluating wildcards
144                 next if (grep -e, glob("$ref $fulref"));
145 
146                 # Accept relative Documentation patches for tools/
147                 if ($f =~ m/tools/) {
148                         my $path = $f;
149                         $path =~ s,(.*)/.*,$1,;
150                         $path =~ s,testing/selftests/bpf,bpf/bpftool,;
151                         next if (grep -e, glob("$path/$ref $path/../$ref $path/$fulref"));
152                 }
153 
154                 # Discard known false-positives
155                 if (defined($false_positives{$f})) {
156                         next if ($false_positives{$f} eq $fulref);
157                 }
158 
159                 if ($fix) {
160                         if (!($ref =~ m/(scripts|Kconfig|Kbuild)/)) {
161                                 $broken_ref{$ref}++;
162                         }
163                 } elsif ($warn) {
164                         print STDERR "Warning: $f references a file that doesn't exist: $fulref\n";
165                 } else {
166                         print STDERR "$f: $fulref\n";
167                 }
168         }
169 }
170 close IN;
171 
172 exit 0 if (!$fix);
173 
174 # Step 2: Seek for file name alternatives
175 print "Auto-fixing broken references. Please double-check the results\n";
176 
177 foreach my $ref (keys %broken_ref) {
178         my $new =$ref;
179 
180         my $basedir = ".";
181         # On translations, only seek inside the translations directory
182         $basedir  = $1 if ($ref =~ m,(Documentation/translations/[^/]+),);
183 
184         # get just the basename
185         $new =~ s,.*/,,;
186 
187         my $f="";
188 
189         # usual reason for breakage: DT file moved around
190         if ($ref =~ /devicetree/) {
191                 # usual reason for breakage: DT file renamed to .yaml
192                 if (!$f) {
193                         my $new_ref = $ref;
194                         $new_ref =~ s/\.txt$/.yaml/;
195                         $f=$new_ref if (-f $new_ref);
196                 }
197 
198                 if (!$f) {
199                         my $search = $new;
200                         $search =~ s,^.*/,,;
201                         $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search);
202                         if (!$f) {
203                                 # Manufacturer name may have changed
204                                 $search =~ s/^.*,//;
205                                 $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search);
206                         }
207                 }
208         }
209 
210         # usual reason for breakage: file renamed to .rst
211         if (!$f) {
212                 $new =~ s/\.txt$/.rst/;
213                 $f=qx(find $basedir -iname $new) if ($new);
214         }
215 
216         # usual reason for breakage: use dash or underline
217         if (!$f) {
218                 $new =~ s/[-_]/[-_]/g;
219                 $f=qx(find $basedir -iname $new) if ($new);
220         }
221 
222         # Wild guess: seek for the same name on another place
223         if (!$f) {
224                 $f = qx(find $basedir -iname $new) if ($new);
225         }
226 
227         my @find = split /\s+/, $f;
228 
229         if (!$f) {
230                 print STDERR "ERROR: Didn't find a replacement for $ref\n";
231         } elsif (scalar(@find) > 1) {
232                 print STDERR "WARNING: Won't auto-replace, as found multiple files close to $ref:\n";
233                 foreach my $j (@find) {
234                         $j =~ s,^./,,;
235                         print STDERR "    $j\n";
236                 }
237         } else {
238                 $f = $find[0];
239                 $f =~ s,^./,,;
240                 print "INFO: Replacing $ref to $f\n";
241                 foreach my $j (qx(git grep -l $ref)) {
242                         qx(sed "s\@$ref\@$f\@g" -i $j);
243                 }
244         }
245 }

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php