From b0601cb34ada6b0d4f29bf33221d1e8584ee50ad Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 10 Nov 2020 12:57:53 -0700 Subject: [CI:DOCS] Restore man page cross-checker Somewhere in the CIv2 migration we lost the man page vs --help cross-checker. Add it back, by adding it into the man-page-check Makefile target; this is part of 'make validate', which is run in CI even on CI:DOCS PRs. As happens when CI doesn't run, things broke. Man pages got out of sync with --help. This PR: 1) Fixes hack/xref-helpmsgs-manpages to deal with the new "Options" (instead of "Flags") form of podman help. #8034 did part of that, but one of my review comments was accidentally left out. 2) Fixes hack/xref-helpmsgs-manpages to deal with the new option syntax in man pages, post- #8292, in which each option is preceded by four hashes so as to make them HTML

elements with named anchors. 3) Fixes man pages that #8292 accidentally missed. 4) Adds man page entries for two flags that got added to podman but not documented (pod create --network-alias, play kube --log-driver) Fixes: #8296 Signed-off-by: Ed Santiago --- Makefile | 5 +---- contrib/cirrus/runner.sh | 4 ++++ docs/source/markdown/podman-create.1.md | 2 +- docs/source/markdown/podman-image-trust.1.md | 8 ++++---- docs/source/markdown/podman-images.1.md | 4 ++-- docs/source/markdown/podman-import.1.md | 2 +- docs/source/markdown/podman-info.1.md | 4 ++-- docs/source/markdown/podman-logs.1.md | 2 +- docs/source/markdown/podman-network-create.1.md | 2 +- docs/source/markdown/podman-play-kube.1.md | 4 ++++ docs/source/markdown/podman-pod-create.1.md | 10 +++++++--- docs/source/markdown/podman-pod-inspect.1.md | 2 +- docs/source/markdown/podman-restart.1.md | 2 +- docs/source/markdown/podman-run.1.md | 2 +- .../source/markdown/podman-system-connection-add.1.md | 4 ++-- docs/source/markdown/podman-system-df.1.md | 2 +- docs/source/markdown/podman-volume-create.1.md | 4 ++-- docs/source/markdown/podman-volume-inspect.1.md | 4 ++-- docs/source/markdown/podman-volume-ls.1.md | 4 ++-- docs/source/markdown/podman-volume-prune.1.md | 2 +- docs/source/markdown/podman-volume-rm.1.md | 4 ++-- hack/podman-commands.sh | 2 +- hack/xref-helpmsgs-manpages | 19 +++++++++++-------- 23 files changed, 55 insertions(+), 43 deletions(-) diff --git a/Makefile b/Makefile index d147987d4..726020cba 100644 --- a/Makefile +++ b/Makefile @@ -392,10 +392,6 @@ docdir: .PHONY: docs docs: $(MANPAGES) ## Generate documentation -.PHONE: xref_helpmsgs_manpages -xref_helpmsgs_manpages: - ./hack/xref-helpmsgs-manpages - install-podman-remote-%-docs: podman-remote docs $(MANPAGES) rm -rf docs/build/remote mkdir -p docs/build/remote @@ -405,6 +401,7 @@ install-podman-remote-%-docs: podman-remote docs $(MANPAGES) .PHONY: man-page-check man-page-check: hack/man-page-checker + hack/xref-helpmsgs-manpages .PHONY: swagger-check swagger-check: diff --git a/contrib/cirrus/runner.sh b/contrib/cirrus/runner.sh index b7e7ab852..4107f3b26 100755 --- a/contrib/cirrus/runner.sh +++ b/contrib/cirrus/runner.sh @@ -50,6 +50,10 @@ function _run_validate() { # Confirm compile via prior task + cache bin/podman --version bin/podman-remote --version + + # FIXME FIXME FIXME: 2020-11-10: remove once Fedora 33 has FindBin + perl -MFindBin -e 0 &>/dev/null || dnf -y install perl-FindBin + make validate # Some items require a build } diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index e18c623ee..5922e0675 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -342,7 +342,7 @@ The initialization time needed for a container to bootstrap. The value can be ex The maximum time allowed to complete the healthcheck before an interval is considered failed. Like start-period, the value can be expressed in a time format such as `1m22s`. The default value is `30s`. -**-h**, **--hostname**=*name* +#### **-h**, **--hostname**=*name* Container host name diff --git a/docs/source/markdown/podman-image-trust.1.md b/docs/source/markdown/podman-image-trust.1.md index 222ecf912..29dfee87e 100644 --- a/docs/source/markdown/podman-image-trust.1.md +++ b/docs/source/markdown/podman-image-trust.1.md @@ -37,15 +37,15 @@ Require signature (“signedBy”). Trust may be updated using the command **podman image trust set** for an existing trust scope. ## OPTIONS -**-h**, **--help** +#### **-h**, **--help** Print usage statement. -**-f**, **--pubkeysfile**=*KEY1* +#### **-f**, **--pubkeysfile**=*KEY1* A path to an exported public key on the local system. Key paths will be referenced in policy.json. Any path to a file may be used but locating the file in **/etc/pki/containers** is recommended. Options may be used multiple times to require an image be signed by multiple keys. The **--pubkeysfile** option is required for the **signedBy** type. -**-t**, **--type**=*value* +#### **-t**, **--type**=*value* The trust type for this policy entry. Accepted values: **signedBy** (default): Require signatures with corresponding list of @@ -59,7 +59,7 @@ Trust may be updated using the command **podman image trust set** for an existin #### **--raw** Output trust policy file as raw JSON -**-j**, **--json** +#### **-j**, **--json** Output trust as JSON for machine parsing ## EXAMPLES diff --git a/docs/source/markdown/podman-images.1.md b/docs/source/markdown/podman-images.1.md index fe5ad6843..531570666 100644 --- a/docs/source/markdown/podman-images.1.md +++ b/docs/source/markdown/podman-images.1.md @@ -15,7 +15,7 @@ Displays locally stored images, their names, and their IDs. ## OPTIONS -**-a**, **--all** +#### **-a**, **--all** Show all images (by default filter out the intermediate image layers). The default is false. @@ -23,7 +23,7 @@ Show all images (by default filter out the intermediate image layers). The defau Show image digests -**-f**, **--filter**=*filter* +#### **-f**, **--filter**=*filter* Filter output based on conditions provided diff --git a/docs/source/markdown/podman-import.1.md b/docs/source/markdown/podman-import.1.md index db0bad241..ba512ca12 100644 --- a/docs/source/markdown/podman-import.1.md +++ b/docs/source/markdown/podman-import.1.md @@ -18,7 +18,7 @@ Note: `:` is a restricted character and cannot be part of the file name. ## OPTIONS -**-c**, **--change**=*instruction* +#### **-c**, **--change**=*instruction* Apply the following possible instructions to the created image: **CMD** | **ENTRYPOINT** | **ENV** | **EXPOSE** | **LABEL** | **STOPSIGNAL** | **USER** | **VOLUME** | **WORKDIR** diff --git a/docs/source/markdown/podman-info.1.md b/docs/source/markdown/podman-info.1.md index 19dd61c15..78895fa15 100644 --- a/docs/source/markdown/podman-info.1.md +++ b/docs/source/markdown/podman-info.1.md @@ -15,11 +15,11 @@ Displays information pertinent to the host, current storage stats, configured co ## OPTIONS -**-D**, **--debug** +#### **-D**, **--debug** Show additional information -**-f**, **--format**=*format* +#### **-f**, **--format**=*format* Change output format to "json" or a Go template. diff --git a/docs/source/markdown/podman-logs.1.md b/docs/source/markdown/podman-logs.1.md index bd8a01840..c93e4c9d7 100644 --- a/docs/source/markdown/podman-logs.1.md +++ b/docs/source/markdown/podman-logs.1.md @@ -30,7 +30,7 @@ to run containers such as CRI-O, the last started container could be from either The latest option is not supported on the remote client. -**-n**, **--names** +#### **-n**, **--names** Output the container name in the log diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md index 4d52749fa..8b8399c3e 100644 --- a/docs/source/markdown/podman-network-create.1.md +++ b/docs/source/markdown/podman-network-create.1.md @@ -22,7 +22,7 @@ Upon completion of creating the network, Podman will display the path to the new Disables the DNS plugin for this network which if enabled, can perform container to container name resolution. -**-d**, **--driver** +#### **-d**, **--driver** Driver to manage the network (default "bridge"). Currently only `bridge` is supported. diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md index d595afb3e..c8391861d 100644 --- a/docs/source/markdown/podman-play-kube.1.md +++ b/docs/source/markdown/podman-play-kube.1.md @@ -42,6 +42,10 @@ The [username[:password]] to use to authenticate with the registry if required. If one or both values are not supplied, a command line prompt will appear and the value can be entered. The password is entered without echo. +#### **--log-driver**=driver + +Set logging driver for all created containers. + #### **--network**=*cni networks* A comma-separated list of the names of CNI networks the pod should join. diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md index 1e1724aeb..6fd42f800 100644 --- a/docs/source/markdown/podman-pod-create.1.md +++ b/docs/source/markdown/podman-pod-create.1.md @@ -63,7 +63,7 @@ The image that will be created for the infra container. Default: "k8s.gcr.io/pau Set a static IP for the pod's shared network. -**-l**, **--label**=*label* +#### **-l**, **--label**=*label* Add metadata to a pod (e.g., --label com.example.key=value). @@ -75,7 +75,7 @@ Read in a line delimited file of labels. Set a static MAC address for the pod's shared network. -**-n**, **--name**=*name* +#### **-n**, **--name**=*name* Assign a name to the pod. @@ -96,6 +96,10 @@ Set network mode for the pod. Supported values are - **port_handler=rootlesskit**: Use rootlesskit for port forwarding. Default. - **port_handler=slirp4netns**: Use the slirp4netns port forwarding. +#### **--network-alias**=strings + +Add a DNS alias for the container. When the container is joined to a CNI network with support for the dnsname plugin, the container will be accessible through this name from other containers in the network. + #### **--no-hosts**=**true**|**false** Disable creation of /etc/hosts for the pod. @@ -104,7 +108,7 @@ Disable creation of /etc/hosts for the pod. Write the pod ID to the file. -**-p**, **--publish**=*port* +#### **-p**, **--publish**=*port* Publish a port or range of ports from the pod to the host. diff --git a/docs/source/markdown/podman-pod-inspect.1.md b/docs/source/markdown/podman-pod-inspect.1.md index c35ebee65..ece3ab885 100644 --- a/docs/source/markdown/podman-pod-inspect.1.md +++ b/docs/source/markdown/podman-pod-inspect.1.md @@ -18,7 +18,7 @@ to run pods such as CRI-O, the last started pod could be from either of those me The latest option is not supported on the remote client. -**-f**, **--format**=*format* +#### **-f**, **--format**=*format* Change the default output format. This can be of a supported type like 'json' or a Go template. diff --git a/docs/source/markdown/podman-restart.1.md b/docs/source/markdown/podman-restart.1.md index 5f83bedde..60c90ada1 100644 --- a/docs/source/markdown/podman-restart.1.md +++ b/docs/source/markdown/podman-restart.1.md @@ -26,7 +26,7 @@ The latest option is not supported on the remote client. #### **--running** Restart all containers that are already in the *running* state. -**-t**, **--time**=*time* +#### **-t**, **--time**=*time* Timeout to wait before forcibly stopping the container. diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 61789dc8f..f67b7c652 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -380,7 +380,7 @@ value can be expressed in a time format such as **1m22s**. The default value is Print usage statement -**-h**, **--hostname**=*name* +#### **-h**, **--hostname**=*name* Container host name diff --git a/docs/source/markdown/podman-system-connection-add.1.md b/docs/source/markdown/podman-system-connection-add.1.md index f314e8c56..c8c6476bf 100644 --- a/docs/source/markdown/podman-system-connection-add.1.md +++ b/docs/source/markdown/podman-system-connection-add.1.md @@ -15,7 +15,7 @@ The user will be prompted for the remote ssh login password or key file pass phr ## OPTIONS -**-d**, **--default**=*false* +#### **-d**, **--default**=*false* Make the new destination the default for this user. @@ -25,7 +25,7 @@ Path to ssh identity file. If the identity file has been encrypted, Podman promp If no identity file is provided and no user is given, Podman defaults to the user running the podman command. Podman prompts for the login password on the remote server. -**-p**, **--port**=*port* +#### **-p**, **--port**=*port* Port for ssh destination. The default value is `22`. diff --git a/docs/source/markdown/podman-system-df.1.md b/docs/source/markdown/podman-system-df.1.md index e0aa2fa47..6c21a20b4 100644 --- a/docs/source/markdown/podman-system-df.1.md +++ b/docs/source/markdown/podman-system-df.1.md @@ -14,7 +14,7 @@ Show podman disk usage Pretty-print images using a Go template -**-v**, **--verbose**[=*true|false*] +#### **-v**, **--verbose**[=*true|false*] Show detailed information on space usage ## EXAMPLE diff --git a/docs/source/markdown/podman-volume-create.1.md b/docs/source/markdown/podman-volume-create.1.md index 9df8e2ec5..4fd911c1f 100644 --- a/docs/source/markdown/podman-volume-create.1.md +++ b/docs/source/markdown/podman-volume-create.1.md @@ -23,11 +23,11 @@ Specify the volume driver name (default local). Print usage statement -**-l**, **--label**=*label* +#### **-l**, **--label**=*label* Set metadata for a volume (e.g., --label mykey=value). -**-o**, **--opt**=*option* +#### **-o**, **--opt**=*option* Set driver specific options. For the default driver, `local`, this allows a volume to be configured to mount a filesystem on the host. diff --git a/docs/source/markdown/podman-volume-inspect.1.md b/docs/source/markdown/podman-volume-inspect.1.md index 5652d9faa..e6be69e73 100644 --- a/docs/source/markdown/podman-volume-inspect.1.md +++ b/docs/source/markdown/podman-volume-inspect.1.md @@ -16,11 +16,11 @@ Volumes can be queried individually by providing their full name or a unique par ## OPTIONS -**-a**, **--all** +#### **-a**, **--all** Inspect all volumes. -**-f**, **--format**=*format* +#### **-f**, **--format**=*format* Format volume output using Go template diff --git a/docs/source/markdown/podman-volume-ls.1.md b/docs/source/markdown/podman-volume-ls.1.md index 353d37fd7..a3f3ff9ba 100644 --- a/docs/source/markdown/podman-volume-ls.1.md +++ b/docs/source/markdown/podman-volume-ls.1.md @@ -14,7 +14,7 @@ flag. Use the **--quiet** flag to print only the volume names. ## OPTIONS -**-f**, **--filter**=*filter* +#### **-f**, **--filter**=*filter* Filter volume output. @@ -26,7 +26,7 @@ Format volume output using Go template. Print usage statement. -**-q**, **--quiet** +#### **-q**, **--quiet** Print volume output in quiet mode. Only print the volume names. diff --git a/docs/source/markdown/podman-volume-prune.1.md b/docs/source/markdown/podman-volume-prune.1.md index 753c816b5..097dded86 100644 --- a/docs/source/markdown/podman-volume-prune.1.md +++ b/docs/source/markdown/podman-volume-prune.1.md @@ -14,7 +14,7 @@ unused volumes. To bypass the confirmation, use the **--force** flag. ## OPTIONS -**-f**, **--force** +#### **-f**, **--force** Do not prompt for confirmation. diff --git a/docs/source/markdown/podman-volume-rm.1.md b/docs/source/markdown/podman-volume-rm.1.md index c831ad7b9..5f2137f73 100644 --- a/docs/source/markdown/podman-volume-rm.1.md +++ b/docs/source/markdown/podman-volume-rm.1.md @@ -15,11 +15,11 @@ Volumes can be removed individually by providing their full name or a unique par ## OPTIONS -**-a**, **--all** +#### **-a**, **--all** Remove all volumes. -**-f**, **--force** +#### **-f**, **--force** Remove a volume by force. If it is being used by containers, the containers will be removed first. diff --git a/hack/podman-commands.sh b/hack/podman-commands.sh index 587cac782..fd4ff2501 100755 --- a/hack/podman-commands.sh +++ b/hack/podman-commands.sh @@ -23,7 +23,7 @@ function die() { # the command name but not its description. function podman_commands() { $PODMAN help "$@" |\ - awk '/^Available Commands:/{ok=1;next}/^Flags:/{ok=0}ok { print $1 }' |\ + awk '/^Available Commands:/{ok=1;next}/^Options:/{ok=0}ok { print $1 }' |\ grep . } diff --git a/hack/xref-helpmsgs-manpages b/hack/xref-helpmsgs-manpages index a7063259f..082cc63f2 100755 --- a/hack/xref-helpmsgs-manpages +++ b/hack/xref-helpmsgs-manpages @@ -248,7 +248,7 @@ sub podman_help { unless $subcommand eq 'help'; # 'help' not in man } } - elsif ($section eq 'flags') { + elsif ($section eq 'options') { # Handle '--foo' or '-f, --foo' if ($line =~ /^\s{1,10}(--\S+)\s/) { print "> podman @_ $1\n" if $debug; @@ -293,7 +293,7 @@ sub podman_man { elsif ($line =~ /^\#\#\s+(SUB)?COMMANDS/) { $section = 'commands'; } - elsif ($line =~ /^\#\#/) { + elsif ($line =~ /^\#\#[^#]/) { $section = ''; } @@ -329,12 +329,15 @@ sub podman_man { } @most_recent_flags = (); - # Handle any variation of '**--foo**, **-f**' - while ($line =~ s/^\*\*((--[a-z0-9-]+)|(-.))\*\*(,\s+)?//g) { - $man{$1} = 1; - - # Keep track of them, in case we see 'Not implemented' below - push @most_recent_flags, $1; + # As of PR #8292, all options are

and anchored + if ($line =~ s/^\#{4}\s+//) { + # Handle any variation of '**--foo**, **-f**' + while ($line =~ s/^\*\*((--[a-z0-9-]+)|(-.))\*\*(,\s+)?//g) { + $man{$1} = 1; + + # Keep track of them, in case we see 'Not implemented' below + push @most_recent_flags, $1; + } } } } -- cgit v1.2.3-54-g00ecf