Merge pull request #7291 from edsantiago/man_page_subcommand_sort

[CI:DOCS] cross-reference .rst files

5 files changed, 131 insertions, 21 deletions

diff --git a/docs/source/Commands.rst b/docs/source/Commands.rst
index a3ff24e89..096bdbedf 100644
--- a/docs/source/Commands.rst
+++ b/docs/source/Commands.rst
@@ -98,7 +98,7 @@ Commands
 
 :doc:`top <markdown/podman-top.1>` Display the running processes of a container
 
-:doc:`umount <markdown/podman-umount.1>` Unmounts working container's root filesystem
+:doc:`unmount <markdown/podman-unmount.1>` Unmounts working container's root filesystem
 
 :doc:`unpause <markdown/podman-unpause.1>` Unpause the processes in one or more containers
 
diff --git a/docs/source/image.rst b/docs/source/image.rst
index fe3a7aa3b..2b0ef3d43 100644
--- a/docs/source/image.rst
+++ b/docs/source/image.rst
@@ -18,7 +18,7 @@ Image
 
 :doc:`load <markdown/podman-load.1>` Load an image from container archive
 
-:doc:`mount <markdown/podman-images-mount.1>` Mount an image's root filesystem.
+:doc:`mount <markdown/podman-image-mount.1>` Mount an image's root filesystem.
 
 :doc:`prune <markdown/podman-image-prune.1>` Remove unused images
 
@@ -40,6 +40,6 @@ Image
 
 :doc:`trust <markdown/podman-image-trust.1>` Manage container image trust policy
 
-:doc:`untag <markdown/podman-untag.1>` Removes one or more names from a locally-stored image
-
 :doc:`unmount <markdown/podman-unmount.1>` Unmount an image's root filesystem
+
+:doc:`untag <markdown/podman-untag.1>` Removes one or more names from a locally-stored image
diff --git a/docs/source/managecontainers.rst b/docs/source/managecontainers.rst
index 2e787c9e9..849fd1d25 100644
--- a/docs/source/managecontainers.rst
+++ b/docs/source/managecontainers.rst
@@ -37,10 +37,10 @@ Manage Containers
 
 :doc:`port <markdown/podman-port.1>` List port mappings or a specific mapping for the container
 
-:doc:`restart <markdown/podman-restart.1>` Restart one or more containers
-
 :doc:`prune <markdown/podman-container-prune.1>` Remove all stopped containers
 
+:doc:`restart <markdown/podman-restart.1>` Restart one or more containers
+
 :doc:`restore <markdown/podman-container-restore.1>` Restores one or more containers from a checkpoint
 
 :doc:`rm <markdown/podman-rm.1>` Remove one or more containers
diff --git a/docs/source/system.rst b/docs/source/system.rst
index e3dfa9d01..566fd1a95 100644
--- a/docs/source/system.rst
+++ b/docs/source/system.rst
@@ -1,7 +1,7 @@
 System
 ======
 
-:doc:`connection <markdown/podman-system-conection.1>` Manage the destination(s) for Podman service(s)
+:doc:`connection <connection>` Manage the destination(s) for Podman service(s)
 
 :doc:`df <markdown/podman-system-df.1>` Show podman disk usage
 
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;