mirror of
https://github.com/containers/podman
synced 2024-10-19 16:54:07 +00:00
Merge pull request #7291 from edsantiago/man_page_subcommand_sort
[CI:DOCS] cross-reference .rst files
This commit is contained in:
commit
d31a881587
|
@ -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
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -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();
|
||||
|
||||
my $retval = xref_by_help($help, $man)
|
||||
+ xref_by_man($help, $man);
|
||||
xref_by_help($help, $man);
|
||||
xref_by_man($help, $man);
|
||||
|
||||
exit !!$retval;
|
||||
xref_rst($help, $rst);
|
||||
|
||||
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;
|
||||
|
|
Loading…
Reference in a new issue