mirror of
https://github.com/git/git
synced 2024-08-25 10:45:59 +00:00
ci: validate "linkgit:" in documentation
It is easy to add incorrect "linkgit:<page>[<section>]" references to our documentation suite. Catch these common classes of errors: * Referring to Documentation/<page>.txt that does not exist. * Referring to a <page> outside the Git suite. In general, <page> must begin with "git". * Listing the manual <section> incorrectly. The first line of the Documentation/<page>.txt must end with "(<section>)". with a new script "ci/lint-gitlink", and drive it from "make check-docs". Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
parent
90f7b16b3a
commit
ab81411ced
|
@ -204,6 +204,7 @@ ifndef V
|
|||
QUIET_DBLATEX = @echo ' ' DBLATEX $@;
|
||||
QUIET_XSLTPROC = @echo ' ' XSLTPROC $@;
|
||||
QUIET_GEN = @echo ' ' GEN $@;
|
||||
QUIET_LINT = @echo ' ' LINT $@;
|
||||
QUIET_STDERR = 2> /dev/null
|
||||
QUIET_SUBDIR0 = +@subdir=
|
||||
QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \
|
||||
|
@ -427,4 +428,7 @@ quick-install-html: require-htmlrepo
|
|||
print-man1:
|
||||
@for i in $(MAN1_TXT); do echo $$i; done
|
||||
|
||||
lint-docs::
|
||||
$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl
|
||||
|
||||
.PHONY: FORCE
|
||||
|
|
71
Documentation/lint-gitlink.perl
Executable file
71
Documentation/lint-gitlink.perl
Executable file
|
@ -0,0 +1,71 @@
|
|||
#!/usr/bin/perl
|
||||
|
||||
use File::Find;
|
||||
use Getopt::Long;
|
||||
|
||||
my $basedir = ".";
|
||||
GetOptions("basedir=s" => \$basedir)
|
||||
or die("Cannot parse command line arguments\n");
|
||||
|
||||
my $found_errors = 0;
|
||||
|
||||
sub report {
|
||||
my ($where, $what, $error) = @_;
|
||||
print "$where: $error: $what\n";
|
||||
$found_errors = 1;
|
||||
}
|
||||
|
||||
sub grab_section {
|
||||
my ($page) = @_;
|
||||
open my $fh, "<", "$basedir/$page.txt";
|
||||
my $firstline = <$fh>;
|
||||
chomp $firstline;
|
||||
close $fh;
|
||||
my ($section) = ($firstline =~ /.*\((\d)\)$/);
|
||||
return $section;
|
||||
}
|
||||
|
||||
sub lint {
|
||||
my ($file) = @_;
|
||||
open my $fh, "<", $file
|
||||
or return;
|
||||
while (<$fh>) {
|
||||
my $where = "$file:$.";
|
||||
while (s/linkgit:((.*?)\[(\d)\])//) {
|
||||
my ($target, $page, $section) = ($1, $2, $3);
|
||||
|
||||
# De-AsciiDoc
|
||||
$page =~ s/{litdd}/--/g;
|
||||
|
||||
if ($page !~ /^git/) {
|
||||
report($where, $target, "nongit link");
|
||||
next;
|
||||
}
|
||||
if (! -f "$basedir/$page.txt") {
|
||||
report($where, $target, "no such source");
|
||||
next;
|
||||
}
|
||||
$real_section = grab_section($page);
|
||||
if ($real_section != $section) {
|
||||
report($where, $target,
|
||||
"wrong section (should be $real_section)");
|
||||
next;
|
||||
}
|
||||
}
|
||||
}
|
||||
close $fh;
|
||||
}
|
||||
|
||||
sub lint_it {
|
||||
lint($File::Find::name) if -f && /\.txt$/;
|
||||
}
|
||||
|
||||
if (!@ARGV) {
|
||||
find({ wanted => \&lint_it, no_chdir => 1 }, $basedir);
|
||||
} else {
|
||||
for (@ARGV) {
|
||||
lint($_);
|
||||
}
|
||||
}
|
||||
|
||||
exit $found_errors;
|
Loading…
Reference in a new issue