Cross-reference *.rst files too

There are a bunch of *.rst files in docs/source, linking sometimes
to man pages and sometimes to other .rst files. These files each
have entries of the following form:

   :doc:`foo <link-to-foo>` Description of foo

...for all podman sub and sub-subcommands 'foo'.

Read all .rst files and make sure that:

  - all entries in a given file are in alphabetical order
  - all link-to-foo targets point to existing doc files
  - every subcommand known by 'podman help' has a corresponding
    doc entry in a .rst file

Signed-off-by: Ed Santiago <santiago@redhat.com>

5 files changed, 116 insertions, 8 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 fd8fe152d..7b617eed7 100755
--- a/hack/xref-helpmsgs-manpages
+++ b/hack/xref-helpmsgs-manpages
@@ -26,8 +26,11 @@ $| = 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;
@@ -99,13 +102,19 @@ 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);
 
+    xref_rst($help, $rst);
+
     exit !!$Errs;
 }
 
+###############################################################################
+# BEGIN cross-referencing
+
 ##################
 #  xref_by_help  #  Find keys in '--help' but not in man
 ##################
@@ -178,6 +187,33 @@ sub xref_by_man {
     }
 }
 
+##############
+#  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'
@@ -317,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;