Merge pull request #22074 from edsantiago/xref-rst
xref-helpmsgs-manpages: cross-check Commands.rst
This commit is contained in:
openshift-merge-bot[bot]
GitHub
commit
8a643c243e
|
|
@ -13,25 +13,25 @@ Commands
|
|||
|
||||
:doc:`commit <markdown/podman-commit.1>` Create new image based on the changed container
|
||||
|
||||
:doc:`container <markdown/podman-container.1>` Manage Containers
|
||||
:doc:`container <markdown/podman-container.1>` Manage containers
|
||||
|
||||
:doc:`cp <markdown/podman-cp.1>` Copy files/folders between a container and the local filesystem
|
||||
|
||||
:doc:`create <markdown/podman-create.1>` Create but do not start a container
|
||||
|
||||
:doc:`diff <markdown/podman-diff.1>` Inspect changes on container's file systems
|
||||
:doc:`diff <markdown/podman-diff.1>` Display the changes to the object's file system
|
||||
|
||||
:doc:`events <markdown/podman-events.1>` Show podman events
|
||||
:doc:`events <markdown/podman-events.1>` Show podman system events
|
||||
|
||||
:doc:`exec <markdown/podman-exec.1>` Run a process in a running container
|
||||
|
||||
:doc:`export <markdown/podman-export.1>` Export container's filesystem contents as a tar archive
|
||||
|
||||
:doc:`export <markdown/podman-farm.1>` Farm out builds to machines running podman for different architectures
|
||||
:doc:`farm <markdown/podman-farm.1>` Farm out builds to remote machines
|
||||
|
||||
:doc:`generate <markdown/podman-generate.1>` Generated structured data
|
||||
:doc:`generate <markdown/podman-generate.1>` Generate structured data based on containers, pods or volumes
|
||||
|
||||
:doc:`healthcheck <markdown/podman-healthcheck.1>` Manage Healthcheck
|
||||
:doc:`healthcheck <markdown/podman-healthcheck.1>` Manage health checks on containers
|
||||
|
||||
:doc:`history <markdown/podman-history.1>` Show history of a specified image
|
||||
|
||||
|
|
@ -45,27 +45,27 @@ Commands
|
|||
|
||||
:doc:`init <markdown/podman-init.1>` Initialize one or more containers
|
||||
|
||||
:doc:`inspect <markdown/podman-inspect.1>` Display the configuration of a container or image
|
||||
:doc:`inspect <markdown/podman-inspect.1>` Display the configuration of object denoted by ID
|
||||
|
||||
:doc:`kill <markdown/podman-kill.1>` Kill one or more running containers with a specific signal
|
||||
|
||||
:doc:`kube <markdown/podman-kube.1>` Play a pod
|
||||
:doc:`kube <markdown/podman-kube.1>` Play containers, pods or volumes from a structured file
|
||||
|
||||
:doc:`load <markdown/podman-load.1>` Load an image from container archive
|
||||
:doc:`load <markdown/podman-load.1>` Load image(s) from a tar archive
|
||||
|
||||
:doc:`login <markdown/podman-login.1>` Log in to a container registry
|
||||
|
||||
:doc:`logout <markdown/podman-logout.1>` Log out of a container registry
|
||||
|
||||
:doc:`logs <markdown/podman-logs.1>` Fetch the logs of a container
|
||||
:doc:`logs <markdown/podman-logs.1>` Fetch the logs of one or more containers
|
||||
|
||||
:doc:`machine <markdown/podman-machine.1>` Manage podman's virtual machine
|
||||
:doc:`machine <markdown/podman-machine.1>` Manage a virtual machine
|
||||
|
||||
:doc:`manifest <markdown/podman-manifest.1>` Create and manipulate manifest lists and image indexes
|
||||
:doc:`manifest <markdown/podman-manifest.1>` Manipulate manifest lists and image indexes
|
||||
|
||||
:doc:`mount <markdown/podman-mount.1>` Mount a working container's root filesystem
|
||||
|
||||
:doc:`network <markdown/podman-network.1>` Manage Networks
|
||||
:doc:`network <markdown/podman-network.1>` Manage networks
|
||||
|
||||
:doc:`pause <markdown/podman-pause.1>` Pause all the processes in one or more containers
|
||||
|
||||
|
|
@ -89,11 +89,11 @@ Commands
|
|||
|
||||
:doc:`run <markdown/podman-run.1>` Run a command in a new container
|
||||
|
||||
:doc:`save <markdown/podman-save.1>` Save image to an archive
|
||||
:doc:`save <markdown/podman-save.1>` Save image(s) to an archive
|
||||
|
||||
:doc:`search <markdown/podman-search.1>` Search registry for image
|
||||
|
||||
:doc:`secret <markdown/podman-secret.1>` Manage podman secrets
|
||||
:doc:`secret <markdown/podman-secret.1>` Manage secrets
|
||||
|
||||
:doc:`start <markdown/podman-start.1>` Start one or more containers
|
||||
|
||||
|
|
@ -113,9 +113,11 @@ Commands
|
|||
|
||||
:doc:`unshare <markdown/podman-unshare.1>` Run a command in a modified user namespace
|
||||
|
||||
:doc:`untag <markdown/podman-untag.1>` Remove one or more names from a locally-stored image
|
||||
:doc:`untag <markdown/podman-untag.1>` Remove a name from a local image
|
||||
|
||||
:doc:`version <markdown/podman-version.1>` Display the Podman Version Information
|
||||
:doc:`update <markdown/podman-update.1>` Update an existing container
|
||||
|
||||
:doc:`version <markdown/podman-version.1>` Display the Podman version information
|
||||
|
||||
:doc:`volume <markdown/podman-volume.1>` Manage volumes
|
||||
|
||||
|
|
|
|||
|
|
@ -1,17 +0,0 @@
|
|||
Volume
|
||||
======
|
||||
:doc:`create <markdown/podman-volume-create.1>` Create a new volume
|
||||
|
||||
:doc:`exists <markdown/podman-volume-exists.1>` Check if the given volume exists
|
||||
|
||||
:doc:`export <markdown/podman-volume-export.1>` Exports volume to external tar
|
||||
|
||||
:doc:`import <markdown/podman-volume-import.1>` Import tarball contents into a podman volume
|
||||
|
||||
:doc:`inspect <markdown/podman-volume-inspect.1>` Display detailed information on one or more volumes
|
||||
|
||||
:doc:`ls <markdown/podman-volume-ls.1>` List volumes
|
||||
|
||||
:doc:`prune <markdown/podman-volume-prune.1>` Remove all unused volumes
|
||||
|
||||
:doc:`rm <markdown/podman-volume-rm.1>` Remove one or more volumes
|
||||
|
|
@ -203,6 +203,8 @@ sub xref_by_help {
|
|||
|
||||
OPTION:
|
||||
for my $k (sort keys %$help) {
|
||||
next if $k =~ /^_/; # metadata ("_desc"). Ignore.
|
||||
|
||||
if (! ref($man)) {
|
||||
# Super-unlikely but I've seen it
|
||||
warn "$ME: 'podman @subcommand' is not documented in man pages!\n";
|
||||
|
|
@ -354,16 +356,38 @@ sub xref_by_man {
|
|||
##############
|
||||
# xref_rst # Cross-check *.rst files against help
|
||||
##############
|
||||
#
|
||||
# This makes a pass over top-level commands only. There is no rst
|
||||
# documentation for any podman subcommands.
|
||||
#
|
||||
sub xref_rst {
|
||||
my ($help, $rst, @subcommand) = @_;
|
||||
my ($help, $rst) = @_;
|
||||
|
||||
|
||||
# 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);
|
||||
# must be referenced in an rst (the converse is not necessarily true)
|
||||
for my $k (sort grep { $_ !~ /^[_-]/ } keys %$help) {
|
||||
if (exists $rst->{$k}) {
|
||||
# Descriptions must match
|
||||
if ($rst->{$k}{_desc} ne $help->{$k}{_desc}) {
|
||||
warn "$ME: podman $k: inconsistent description in $rst->{$k}{_source}:\n";
|
||||
warn " help: '$help->{$k}{_desc}'\n";
|
||||
warn " rst: '$rst->{$k}{_desc}'\n";
|
||||
++$Errs;
|
||||
}
|
||||
}
|
||||
else {
|
||||
warn "$ME: Not found in rst: $k\n";
|
||||
++$Errs;
|
||||
}
|
||||
}
|
||||
|
||||
# Now the other way around: look for anything in Commands.rst that is
|
||||
# not in podman --help
|
||||
for my $k (sort grep { $rst->{$_}{_source} =~ /Commands.rst/ } keys %$rst) {
|
||||
if ($k ne 'Podman' && ! exists $help->{$k}) {
|
||||
warn "$ME: 'podman $k' found in $rst->{$k}{_source} but not 'podman help'\n";
|
||||
++$Errs;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -381,7 +405,17 @@ sub podman_help {
|
|||
or die "$ME: Cannot fork: $!\n";
|
||||
my $section = '';
|
||||
while (my $line = <$fh>) {
|
||||
chomp $line;
|
||||
|
||||
# First line of --help is a short command description. We compare it
|
||||
# (in a later step) against the blurb in Commands.rst.
|
||||
# FIXME: we should crossref against man pages, but as of 2024-03-18
|
||||
# it would be way too much work to get those aligned.
|
||||
$help{_desc} //= $line;
|
||||
|
||||
# Cobra is blessedly consistent in its output:
|
||||
# [command blurb]
|
||||
# Description: ...
|
||||
# Usage: ...
|
||||
# Available Commands:
|
||||
# ....
|
||||
|
|
@ -840,14 +874,8 @@ sub podman_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} //= { };
|
||||
$subcommand_href = $rst{$command} //= { _source => $rst };
|
||||
}
|
||||
|
||||
my $previous_subcommand = '';
|
||||
|
|
@ -855,15 +883,20 @@ sub podman_rst {
|
|||
if ($line =~ /^:doc:`(\S+)\s+<(.*?)>`\s+(.*)/) {
|
||||
my ($subcommand, $target, $desc) = ($1, $2, $3);
|
||||
|
||||
# Check that entries are in alphabetical order
|
||||
# Check that entries are in alphabetical order, and not dups
|
||||
if ($subcommand lt $previous_subcommand) {
|
||||
warn "$ME: $rst:$.: '$previous_subcommand' and '$subcommand' are out of order\n";
|
||||
++$Errs;
|
||||
}
|
||||
if ($subcommand eq $previous_subcommand) {
|
||||
warn "$ME: $rst:$.: duplicate '$subcommand'\n";
|
||||
++$Errs;
|
||||
}
|
||||
$previous_subcommand = $subcommand;
|
||||
|
||||
# Mark this subcommand as documented.
|
||||
$subcommand_href->{$subcommand}{_desc} = $desc;
|
||||
$subcommand_href->{$subcommand}{_source} = $rst;
|
||||
|
||||
# Check for invalid links. These will be one of two forms:
|
||||
# <markdown/foo.1> -> markdown/foo.1.md
|
||||
|
|
@ -873,10 +906,20 @@ sub podman_rst {
|
|||
warn "$ME: $rst:$.: '$subcommand' links to nonexistent $target\n";
|
||||
++$Errs;
|
||||
}
|
||||
|
||||
my $expect = "markdown/podman-$subcommand.1";
|
||||
if ($subcommand eq 'Podman') {
|
||||
$expect = "markdown/podman.1";
|
||||
}
|
||||
if ($target ne $expect) {
|
||||
warn "$ME: $rst:$.: '$subcommand' links to $target (expected '$expect')\n";
|
||||
++$Errs;
|
||||
}
|
||||
}
|
||||
else {
|
||||
if (! -e "$Docs_Path/$target.rst") {
|
||||
warn "$ME: $rst:$.: '$subcommand' links to nonexistent $target.rst\n";
|
||||
++$Errs;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -130,7 +130,7 @@ $mclone->{events}{"--format"}{".Attributes"} = 0;
|
|||
$mclone->{events}{"--format"}{".Image"} = '...';
|
||||
$mclone->{events}{"--format"}{".Status"} = 1;
|
||||
$hclone->{events}{"--format"}{".Status"} = '...';
|
||||
$mclone->{events}{"--format"}{".ToHumanReadable"} = 3;
|
||||
$mclone->{pod}{ps}{"--format"}{".Label"} = 3;
|
||||
$mclone->{ps}{"--format"}{".Label"} = 0;
|
||||
# --format is documented, with a table, but one entry missing
|
||||
delete $mclone->{events}{"--format"}{".Type"};
|
||||
|
|
@ -154,11 +154,11 @@ test_xref("xref_by_help() injection", $hclone, $mclone,
|
|||
"'podman events --format {{.Attributes' is a nested structure. Please add '...' to man page.",
|
||||
"'podman events --format {{.Image' is a simple value, not a nested structure. Please remove '...' from man page.",
|
||||
"'podman events --format {{.Status' is a nested structure, but the man page documents it as a function?!?",
|
||||
"'podman events --format {{.ToHumanReadable' is a function that calls for 1 args; the man page lists 3. Please fix the man page.",
|
||||
"'podman events --format <TAB>' lists '.Type', which is not in podman-events.1.md",
|
||||
"'podman --help' lists 'new-command-in-help', which is not in podman.1.md",
|
||||
"'podman partlydocumented' is not documented in man pages!",
|
||||
"'podman pod inspect --help' lists '-l', which is not in podman-pod-inspect.1.md",
|
||||
"'podman pod ps --format {{.Label' is a function that calls for 1 args; the man page lists 3. Please fix the man page.",
|
||||
"'podman ps --format {{.Label' is a function that calls for 1 args. Please investigate what those are, then add them to the man page. E.g., '.Label *bool*' or '.Label *path* *bool*'",
|
||||
"'podman secret --help' lists 'subcommand-in-help', which is not in podman-secret.1.md",
|
||||
],
|
||||
|
|
|
|||
Loading…
Reference in New Issue