summaryrefslogtreecommitdiff
path: root/hack/xref-helpmsgs-manpages
diff options
context:
space:
mode:
Diffstat (limited to 'hack/xref-helpmsgs-manpages')
-rwxr-xr-xhack/xref-helpmsgs-manpages138
1 files changed, 124 insertions, 14 deletions
diff --git a/hack/xref-helpmsgs-manpages b/hack/xref-helpmsgs-manpages
index 16b596589..7b617eed7 100755
--- a/hack/xref-helpmsgs-manpages
+++ b/hack/xref-helpmsgs-manpages
@@ -26,8 +26,14 @@ $| = 1;
my $Default_Podman = './bin/podman';
my $PODMAN = $ENV{PODMAN} || $Default_Podman;
+# Path to all doc files, including .rst and (down one level) markdown
+my $Docs_Path = 'docs/source';
+
# Path to podman markdown source files (of the form podman-*.1.md)
-my $Markdown_Path = 'docs/source/markdown';
+my $Markdown_Path = "$Docs_Path/markdown";
+
+# Global error count
+my $Errs = 0;
# END user-customizable section
###############################################################################
@@ -96,35 +102,38 @@ sub main {
my $help = podman_help();
my $man = podman_man('podman');
+ my $rst = podman_rst();
+
+ xref_by_help($help, $man);
+ xref_by_man($help, $man);
- my $retval = xref_by_help($help, $man)
- + xref_by_man($help, $man);
+ xref_rst($help, $rst);
- exit !!$retval;
+ exit !!$Errs;
}
+###############################################################################
+# BEGIN cross-referencing
+
##################
# xref_by_help # Find keys in '--help' but not in man
##################
sub xref_by_help {
my ($help, $man, @subcommand) = @_;
- my $errs = 0;
for my $k (sort keys %$help) {
if (exists $man->{$k}) {
if (ref $help->{$k}) {
- $errs += xref_by_help($help->{$k}, $man->{$k}, @subcommand, $k);
+ xref_by_help($help->{$k}, $man->{$k}, @subcommand, $k);
}
# Otherwise, non-ref is leaf node such as a --option
}
else {
my $man = $man->{_path} || 'man';
warn "$ME: podman @subcommand --help lists $k, but $k not in $man\n";
- ++$errs;
+ ++$Errs;
}
}
-
- return $errs;
}
#################
@@ -137,13 +146,11 @@ sub xref_by_help {
sub xref_by_man {
my ($help, $man, @subcommand) = @_;
- my $errs = 0;
-
# FIXME: this generates way too much output
for my $k (grep { $_ ne '_path' } sort keys %$man) {
if (exists $help->{$k}) {
if (ref $man->{$k}) {
- $errs += xref_by_man($help->{$k}, $man->{$k}, @subcommand, $k);
+ xref_by_man($help->{$k}, $man->{$k}, @subcommand, $k);
}
}
elsif ($k ne '--help' && $k ne '-h') {
@@ -175,13 +182,38 @@ sub xref_by_man {
next if "@subcommand" eq 'system' && $k eq 'service';
warn "$ME: podman @subcommand: $k in $man, but not --help\n";
- ++$errs;
+ ++$Errs;
}
}
+}
- return $errs;
+##############
+# xref_rst # Cross-check *.rst files against help
+##############
+sub xref_rst {
+ my ($help, $rst, @subcommand) = @_;
+
+ # Cross-check against rst (but only subcommands, not options).
+ # We key on $help because that is Absolute Truth: anything in podman --help
+ # must be referenced in an rst (the converse is not true).
+ for my $k (sort grep { $_ !~ /^-/ } keys %$help) {
+ # Check for subcommands, if any (eg podman system -> connection -> add)
+ if (ref $help->{$k}) {
+ xref_rst($help->{$k}, $rst->{$k}, @subcommand, $k);
+ }
+
+ # Check that command is mentioned in at least one .rst file
+ if (! exists $rst->{$k}{_desc}) {
+ my @podman = ("podman", @subcommand, $k);
+ warn "$ME: no link in *.rst for @podman\n";
+ ++$Errs;
+ }
+ }
}
+# END cross-referencing
+###############################################################################
+# BEGIN data gathering
#################
# podman_help # Parse output of 'podman [subcommand] --help'
@@ -249,6 +281,7 @@ sub podman_man {
or die "$ME: Cannot read $manpath: $!\n";
my $section = '';
my @most_recent_flags;
+ my $previous_subcmd = '';
while (my $line = <$fh>) {
chomp $line;
next unless $line; # skip empty lines
@@ -278,6 +311,11 @@ sub podman_man {
elsif ($line =~ /^\|\s+(\S+)\s+\|\s+\[\S+\]\((\S+)\.1\.md\)/) {
# $1 will be changed by recursion _*BEFORE*_ left-hand assignment
my $subcmd = $1;
+ if ($previous_subcmd gt $subcmd) {
+ warn "$ME: $subpath: '$previous_subcmd' and '$subcmd' are out of order\n";
+ ++$Errs;
+ }
+ $previous_subcmd = $subcmd;
$man{$subcmd} = podman_man($2);
}
}
@@ -315,4 +353,76 @@ sub podman_man {
}
+################
+# podman_rst # Parse contents of docs/source/*.rst
+################
+sub podman_rst {
+ my %rst;
+
+ # Read all .rst files, looking for ":doc:`subcmd <target>` description"
+ for my $rst (glob "$Docs_Path/*.rst") {
+ open my $fh, '<', $rst
+ or die "$ME: Cannot read $rst: $!\n";
+
+ # The basename of foo.rst is usually, but not always, the name of
+ # a podman subcommand. There are a few special cases:
+ (my $command = $rst) =~ s!^.*/(.*)\.rst!$1!;
+
+ my $subcommand_href = \%rst;
+ if ($command eq 'Commands') {
+ ;
+ }
+ elsif ($command eq 'managecontainers') {
+ $subcommand_href = $rst{container} //= { };
+ }
+ elsif ($command eq 'connection') {
+ $subcommand_href = $rst{system}{connection} //= { };
+ }
+ else {
+ $subcommand_href = $rst{$command} //= { };
+ }
+
+ my $previous_subcommand = '';
+ while (my $line = <$fh>) {
+ if ($line =~ /^:doc:`(\S+)\s+<(.*?)>`\s+(.*)/) {
+ my ($subcommand, $target, $desc) = ($1, $2, $3);
+
+ # Check that entries are in alphabetical order
+ if ($subcommand lt $previous_subcommand) {
+ warn "$ME: $rst:$.: '$previous_subcommand' and '$subcommand' are out of order\n";
+ ++$Errs;
+ }
+ $previous_subcommand = $subcommand;
+
+ # Mark this subcommand as documented.
+ $subcommand_href->{$subcommand}{_desc} = $desc;
+
+ # Check for invalid links. These will be one of two forms:
+ # <markdown/foo.1> -> markdown/foo.1.md
+ # <foo> -> foo.rst
+ if ($target =~ m!^markdown/!) {
+ if (! -e "$Docs_Path/$target.md") {
+ warn "$ME: $rst:$.: '$subcommand' links to nonexistent $target\n";
+ ++$Errs;
+ }
+ }
+ else {
+ if (! -e "$Docs_Path/$target.rst") {
+ warn "$ME: $rst:$.: '$subcommand' links to nonexistent $target.rst\n";
+ }
+ }
+ }
+ }
+ close $fh;
+ }
+
+ # Special case: 'image trust set/show' are documented in image-trust.1
+ $rst{image}{trust}{$_} = { _desc => 'ok' } for (qw(set show));
+
+ return \%rst;
+}
+
+# END data gathering
+###############################################################################
+
1;