update help output suggestions to display correct cmd format

[juanvallejo]

Related BZ: https://bugzilla.redhat.com/show_bug.cgi?id=1313198

When displaying help output for commands that invoke the templates.ActsAsRootCommand method, suggested commands are displayed out of order:

$ oc set -h

Configure application resources

These commands help you make changes to existing application resources.

Usage:
  oc set COMMAND [options]

Replication controllers, deployments, and daemon sets:
  env             Update environment variables on a pod template
  volumes         Update volumes on a pod template
  probe           Update a probe on a pod template
  deployment-hook Update a deployment hook on a deployment config

Manage application flows:
  triggers        Update the triggers on a build or deployment config
  build-hook      Update a build hook on a build config

Use "oc set help <command>" for more information about a given command.
Use "oc options" for a list of global command-line options (applies to all commands).

Use "oc set help " should be Use "oc help set "
When invoking help for sub-commands, such as oc set triggers -h, the suggested line for Use "oc options"... adds on the immediate parent command:
Use "oc set options"...

A suggested solution for this would be to display help output for these commands without calling templates.ActsAsRootCommand method, and use a non-root usage template instead:

Configure application resources

These commands help you make changes to existing application resources.

Usage:
  oc set COMMAND [options]

Available Commands:
  env             Update environment variables on a pod template
  volumes         Update volumes on a pod template
  probe           Update a probe on a pod template
  deployment-hook Update a deployment hook on a deployment config
  triggers        Update the triggers on a build or deployment config
  build-hook      Update a build hook on a build config

Use "oc help <command>" for more information about a given command.
Use "oc options" for a list of global command-line options (applies to all commands).

Sub-commands also display the correct usage suggested by the two bottom lines. The only immediate difference is that all available sub-commands are not formatted in groups.

cc @deads2k @fabianofranz @liggitt

EDIT: The only commands currently affected by this are oc set -h and oadm policy -h. If we still wish to print available sub-commands for these commands in groups, we could make a function elsewhere that does this

[fabianofranz]

@juanvallejo no longer WIP?

[juanvallejo]

@fabianofranz Ah, the current pushed changes are complete, but I was a bit hesitant to remove the "WIP" tag in case anyone else had a better solution

[fabianofranz]

@juanvallejo ok, let me take a look.

[juanvallejo]

@fabianofranz Hm, do you think it would be a good idea to make a separate function that "parses" command groups for these two commands (oadm policy and oc set)? I think that was a big reason why the template for "root" commands was being used in the first place

EDIT: By "parse" I meant making sure command groups get printed similar to how they are printed at the moment using the root command template

[fabianofranz]

What about changing how we suggest it, to the --help flag instead of the help subcommand? I didn't check if it would fit every scenario (oc, openshift cli, this bug, etc) but you would change this line to something like

Use "{{$rootCmd}} <command> --help ..." 

I think the flag is a more standard way of accessing help anyway.

[fabianofranz]

Apart this bug, I think this templating system could make good use of some refactorings. It's a little confusing and hard to follow. As far as possible we shouldn't need to mark stuff, for example the help template should just print separate groups if there are groups but print "Available Commands" not grouped if there aren't, etc.

[juanvallejo]

@fabianofranz

Apart this bug, I think this templating system could make good use of some refactorings. It's a little confusing and hard to follow.

I agree, I think it might be a good idea to not have child commands "act as root commands" if they are only going to make use of the same usage template as root commands.

What about changing how we suggest it, to the --help flag instead of the help subcommand? I didn't check if it would fit every scenario (oc, openshift cli, this bug, etc) but you would change this line to something like...

Hm, this could also work, I was finishing working on this current solution at the time, but would also be on board with doing this. Could you take a look at the new commit, and see if we could use these changes as well? Below is the new output:

$ oc -h

Use "oc help  <command>" for more information about a given command.
Use "oc options" for a list of global command-line options (applies to all commands).

$ openshift -h

Use "openshift help  <command>" for more information about a given command.
Use "openshift options" for a list of global command-line options (applies to all commands).

$ openshift cli -h

Use "openshift cli help  <command>" for more information about a given command.
Use "openshift cli options" for a list of global command-line options (applies to all commands).

$ openshift cli set -h

Use "openshift help cli set  <command>" for more information about a given command.
Use "openshift cli options" for a list of global command-line options (applies to all commands).

$ oc set -h

Use "oc help set  <command>" for more information about a given command.
Use "oc options" for a list of global command-line options (applies to all commands).

$ openshift admin policy -h

Use "openshift help admin policy  <command>" for more information about a given command.
Use "openshift admin options" for a list of global command-line options (applies to all commands).

$ oadm policy -h

Use "oadm help policy  <command>" for more information about a given command.
Use "oadm options" for a list of global command-line options (applies to all commands).

These changes support this format recursively, so if a nested command later on is made to "act as root command", it would keep this correct format as well

[juanvallejo]

[test]

[juanvallejo]

@openshift-bot, the last build failed from the following flakes:

• check failed on: ImageStreamTag possibly should not return 404 when a status exists and the image does not #5391

re[test]

[fabianofranz]

I'm not opposed to the new version, but I think it's unnecessary complexity.

Unless I'm missing something, just changing it to Use "{{$rootCmd}} <command> --help" would fix the issue, and even make it simpler to users because they don't have to guess where help is supposed to be (before/after cli, before/after a command name that has subcommands, etc). --help goes always at the end. ;) Also it seems that kubectl is suggesting --help too.

Feel free to disagree, but I'd go with the simpler solution and eventually work on a refactoring to make this better structured.

[openshift-bot]

Evaluated for origin test up to 16e318e

[juanvallejo]

@fabianofranz Thanks for the feedback!

I'm not opposed to the new version, but I think it's unnecessary complexity.
Unless I'm missing something, just changing it to Use "{{$rootCmd}} --help" would fix the issue

I think this is a very valid point, I have gone ahead and updated the help suggestion to just include --help at the end.

I went ahead and saved the other code locally in case there is an actual use-case for it in the future :)

[fabianofranz]

Sounds good, thanks! LGTM, [merge].

[openshift-bot]

continuous-integration/openshift-jenkins/merge SUCCESS (https://ci.openshift.redhat.com/jenkins/job/test_pr_origin/7611/) (Image: devenv-rhel7_4776)

[openshift-bot]

Evaluated for origin merge up to 16e318e

[openshift-bot]

continuous-integration/openshift-jenkins/test SUCCESS (https://ci.openshift.redhat.com/jenkins/job/test_pr_origin/7589/)