Fix help commands to show short and long description. #2564

rhatdan · 2019-03-06T22:10:49Z

Cleanup lots of help information to look good when displayed.

Signed-off-by: Daniel J Walsh dwalsh@redhat.com

[root@localhost ~]# podman build --help
Builds an OCI or Docker image using instructions from one
or more Dockerfiles and a specified build context directory.

Usage:
  podman build [flags] CONTEXT

Examples:
  podman build .
  podman build --cert-dir ~/auth --creds=username:password -t imageName -f Dockerfile.simple .
  podman build --layers --force-rm --tag imageName .

Flags:
      --add-host host:ip                           add a custom host-to-IP mapping (host:ip) (default [])
      --annotation strings                         Set metadata for an image (default [])
      --authfile string                            path of the authentication file. Default is ${XDG_RUNTIME_DIR}/containers/auth.json
      --build-arg argument=value                   argument=value to supply to the builder
      --cache-from string                          Images to utilise as potential cache sources. The build process does not currently support caching so this is a NOOP.
      --cap-add strings                            add the specified capability when running (default [])
      --cap-drop strings                           drop the specified capability when running (default [])
      --cert-dir string                            use certificates at the specified path to access the registry
      --cgroup-parent string                       optional parent cgroup for the container
      --cni-plugin-path path                       path of CNI network plugins (default "/usr/libexec/cni:/opt/cni/bin")
      --compress                                   This is legacy option, which has no effect on the image
      --cpu-period uint                            limit the CPU CFS (Completely Fair Scheduler) period
      --cpu-quota int                              limit the CPU CFS (Completely Fair Scheduler) quota
  -c, --cpu-shares uint                            CPU shares (relative weight)
      --cpuset-cpus string                         CPUs in which to allow execution (0-3, 0,1)

Podman build help after:

# podman build --help
Build an image using instructions from Dockerfiles

Description:

Builds an OCI or Docker image using instructions from one or more Dockerfiles and a specified build context directory.

Usage:
  podman build [flags] CONTEXT

Examples:
  podman build .
  podman build --cert-dir ~/auth --creds=username:password -t imageName -f Dockerfile.simple .
  podman build --layers --force-rm --tag imageName .

Flags:
      --add-host host:ip                           add a custom host-to-IP mapping (host:ip) (default [])
      --annotation strings                         Set metadata for an image (default [])
      --authfile string                            path of the authentication file. Default is ${XDG_RUNTIME_DIR}/containers/auth.json
      --build-arg argument=value                   argument=value to supply to the builder
      --cache-from string                          Images to utilise as potential cache sources. The build process does not currently support caching so this is a NOOP.
      --cap-add strings                            add the specified capability when running (default [])
      --cap-drop strings                           drop the specified capability when running (default [])
      --cert-dir string                            use certificates at the specified path to access the registry
      --cgroup-parent string                       optional parent cgroup for the container
      --cni-plugin-path path                       path of CNI network plugins (default "/usr/libexec/cni:/opt/cni/bin")
      --compress                                   This is legacy option, which has no effect on the image
      --cpu-period uint                            limit the CPU CFS (Completely Fair Scheduler) period
      --cpu-quota int                              limit the CPU CFS (Completely Fair Scheduler) quota
  -c, --cpu-shares uint                            CPU shares (relative weight)

Podman diff help before:

# podman diff --help
Displays changes on a container or image's filesystem.  The
	container or image will be compared to its parent layer

Usage:
  podman diff [flags] CONTAINER | IMAGE

Examples:
  podman diff imageID
  podman diff ctrID
  podman diff --format json redis:alpine

Flags:
      --format string   Change the output format
  -h, --help            help for diff

Podman diff help after:

# podman diff --help
Inspect changes on container's file systems

Description:

Displays changes on a container or image's filesystem.  The container or image will be compared to its parent layer.

Usage:
  podman diff [flags] CONTAINER | IMAGE

Examples:
  podman diff imageID
  podman diff ctrID
  podman diff --format json redis:alpine

Flags:
      --format string   Change the output format
  -h, --help            help for diff

TomSweeneyRedHat · 2019-03-06T22:44:11Z

cmd/podman/run.go

@@ -39,6 +39,8 @@ var (

 func init() {
 	runCommand.Command = _runCommand
+	runCommand.SetHelpTemplate(HelpTemplate())
+	runCommand.SetHelpTemplate(HelpTemplate())


edsantiago · 2019-03-06T23:31:37Z

cmd/podman/common.go

+
+Description:
+
+{{.Long}}


For consistency with the rest of the output, would you consider (1) removing the empty line between Description: and the text, and (2) indenting {{.Long}} two spaces?

Update: well, that's harder than I thought: multi-line descriptions (import, info, inspect, ...) would need to be manually indented. I see no clean way to deal with this but hope someone can.

yeah, I think similar fun here as with the examples. They'd have to be manually indented. I think "as is" is probably the best case.

I will remove the line for now.

TomSweeneyRedHat · 2019-03-07T00:12:36Z

Top biting this one, gonna rekick.

TomSweeneyRedHat · 2019-03-07T00:12:46Z

bot, retest this please.

TomSweeneyRedHat · 2019-03-07T00:13:00Z

One probable small change, otherwise LGTM.

edsantiago

LGTM; only minor comments.

I see a lot of 'The container name or ID can be used.'; are those really necessary?

grep -L suggests that healthcheck_run.go might be another candidate for a Description.

edsantiago · 2019-03-07T00:41:21Z

cmd/podman/exec.go

-	podman exec
-
-	Run a command in a running container
+	execDescription = `Execute the specified command inside of  a running container.


No need for 'of'; just 'inside a container' is best. Also, extra space character.

edsantiago · 2019-03-07T00:43:47Z

cmd/podman/cp.go

@@ -27,8 +27,9 @@ import (
 var (
 	cpCommand cliconfig.CpValues

-	cpDescription = "Copy files/folders between a container and the local filesystem"
-	_cpCommand    = &cobra.Command{
+	cpDescription = `The podman cp utility copies the contents of SRC_PATH to the DEST_PATH.  You can copy from the container's file system to the local machine or the reverse, from the local filesystem to the container. If - is specified for either the SRC_PATH or DEST_PATH, you can also stream a tar archive from STDIN or to STDOUT. The CONTAINER can be a running or stopped container.  The SRC_PATH or DEST_PATH can be a file or directory.


The convention I see for the most part is to document as 'Action blah blah'; It feels jarring to see this one as 'The podman cp utility ...'. How about just 'Copy the contents'?

Fixed to `Commant copies ...

edsantiago · 2019-03-07T00:48:38Z

cmd/podman/inspect.go

-	_inspectCommand    = &cobra.Command{
+	inspectDescription = `This displays the low-level information on containers and images identified by name or ID.
+
+By default, this will render all results in a JSON array. If the container and image have the same name, this command returns the container JSON.`


I know this isn't part of your commit, but why not change that to something more readable such as 'If given a name that matches both a container and an image, this command inspects the container.'

edsantiago · 2019-03-07T00:50:21Z

cmd/podman/logs.go

@@ -15,8 +15,10 @@ import (

 var (
 	logsCommand     cliconfig.LogsValues
-	logsDescription = "The podman logs command batch-retrieves whatever logs are present for a container at the time of execution.  This does not guarantee execution" +
-		"order when combined with podman run (i.e. your run may not have generated any logs at the time you execute podman logs"
+	logsDescription = `The podman logs command batch-retrieves whatever logs are present for a container at the time of execution.


Same principle as cp above: 'Retrieves whatever logs ...'

edsantiago · 2019-03-07T00:54:22Z

cmd/podman/rm.go

-Podman rm will remove one or more containers from the host.
-The container name or ID can be used. This does not remove images.
-Running containers will not be removed without the -f option.
+	rmDescription = fmt.Sprintf(`Podman rm will remove one or more containers from the host. The container name or ID can be used.


Another unnecessary Podman; just 'Remove one or more...' might be better.

edsantiago · 2019-03-07T00:57:11Z

cmd/podman/varlink.go


-	run varlink interface
+Tools speaking valink protocol can remotely manage pods, containers and images.


Typo (valink)

edsantiago · 2019-03-07T17:36:57Z

cmd/podman/exists.go

-`
-	containerExistsDescription = `
-	podman container exists
+	containerExistsDescription = `If an container exists in local storage, podman container exists exits with 0, otherwise exit code will be 1.`


a container, not an; likewise for pod below.

Modified the comment.

edsantiago · 2019-03-07T17:38:31Z

cmd/podman/inspect.go

-	_inspectCommand    = &cobra.Command{
+	inspectDescription = `This displays the low-level information on containers and images identified by name or ID.
+
+  If given a namee that matches both a container and an image, this command inspects the container.  By default, this will render all results in a JSON array.`


Typo: namee

edsantiago · 2019-03-07T17:41:59Z

cmd/podman/pod_unpause.go

@@ -12,8 +12,10 @@ import (

 var (
 	podUnpauseCommand     cliconfig.PodUnpauseValues
-	podUnpauseDescription = `Unpauses one or more pods.  The pod name or ID can be used.`
-	_podUnpauseCommand    = &cobra.Command{
+	podUnpauseDescription = `The podman unpause command will unpause "paused" all containers assigned to the pod.


Was that meant to be will unpause all "paused" containers? I'm not sure how to parse it otherwise.

edsantiago · 2019-03-07T17:44:26Z

cmd/podman/top.go

-the latest container.
-%s
-`, getDescriptorString())
+	topDescription = fmt.Sprintf(`Similare to system top command.


Typo: Similare

edsantiago · 2019-03-07T17:46:35Z

cmd/podman/volume_prune.go

@@ -16,12 +16,9 @@ import (

 var (
 	volumePruneCommand     cliconfig.VolumePruneValues
-	volumePruneDescription = `
-podman volume prune
+	volumePruneDescription = `Command prompts for confirmation if not using the --force flag.


No longer says what this command does ("Remove all unused volumes"). Was that intentional?

Cleanup lots of help information to look good when displayed. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>

openshift-ci-robot · 2019-03-07T21:45:46Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: edsantiago, rhatdan

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [rhatdan]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

edsantiago · 2019-03-07T21:46:01Z

/lgtm

Thank you for your patience with my nits

openshift-ci-robot requested review from mheon and vrothberg March 6, 2019 22:10

openshift-ci-robot added approved Indicates a PR has been approved by an approver from all required OWNERS files. size/L labels Mar 6, 2019

TomSweeneyRedHat reviewed Mar 6, 2019

View reviewed changes

edsantiago reviewed Mar 6, 2019

View reviewed changes

edsantiago suggested changes Mar 7, 2019

View reviewed changes

rhatdan force-pushed the cleanup branch 2 times, most recently from 0a5c7bf to 034b879 Compare March 7, 2019 13:56

edsantiago reviewed Mar 7, 2019

View reviewed changes

Fix help commands to show short and long description.

9a39c60

Cleanup lots of help information to look good when displayed. Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>

rhatdan force-pushed the cleanup branch from 034b879 to 9a39c60 Compare March 7, 2019 18:47

edsantiago approved these changes Mar 7, 2019

View reviewed changes

openshift-ci-robot assigned edsantiago Mar 7, 2019

openshift-ci-robot added the lgtm Indicates that a PR is ready to be merged. label Mar 7, 2019

openshift-merge-robot merged commit 94e89fc into containers:master Mar 7, 2019

github-actions bot added the locked - please file new issue/PR Assist humans wanting to comment on an old issue or PR with locked comments. label Sep 27, 2023

github-actions bot locked as resolved and limited conversation to collaborators Sep 27, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix help commands to show short and long description. #2564

Fix help commands to show short and long description. #2564

rhatdan commented Mar 6, 2019 •

edited by TomSweeneyRedHat

Loading

TomSweeneyRedHat Mar 6, 2019

rhatdan Mar 7, 2019

edsantiago Mar 6, 2019

edsantiago Mar 6, 2019

TomSweeneyRedHat Mar 7, 2019

rhatdan Mar 7, 2019

TomSweeneyRedHat commented Mar 7, 2019

TomSweeneyRedHat commented Mar 7, 2019

TomSweeneyRedHat commented Mar 7, 2019

edsantiago left a comment

edsantiago Mar 7, 2019

rhatdan Mar 7, 2019

edsantiago Mar 7, 2019

rhatdan Mar 7, 2019

edsantiago Mar 7, 2019

rhatdan Mar 7, 2019

edsantiago Mar 7, 2019

rhatdan Mar 7, 2019

edsantiago Mar 7, 2019

rhatdan Mar 7, 2019

edsantiago Mar 7, 2019

rhatdan Mar 7, 2019

edsantiago Mar 7, 2019

rhatdan Mar 7, 2019

edsantiago Mar 7, 2019

rhatdan Mar 7, 2019

edsantiago Mar 7, 2019

rhatdan Mar 7, 2019

edsantiago Mar 7, 2019

rhatdan Mar 7, 2019

edsantiago Mar 7, 2019

rhatdan Mar 7, 2019

openshift-ci-robot commented Mar 7, 2019

edsantiago commented Mar 7, 2019


		run varlink interface
		Tools speaking valink protocol can remotely manage pods, containers and images.


		Description:

		{{.Long}}

Fix help commands to show short and long description. #2564

Fix help commands to show short and long description. #2564

Conversation

rhatdan commented Mar 6, 2019 • edited by TomSweeneyRedHat Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TomSweeneyRedHat commented Mar 7, 2019

TomSweeneyRedHat commented Mar 7, 2019

TomSweeneyRedHat commented Mar 7, 2019

edsantiago left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

openshift-ci-robot commented Mar 7, 2019

edsantiago commented Mar 7, 2019

rhatdan commented Mar 6, 2019 •

edited by TomSweeneyRedHat

Loading