Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fixes and docs for usage as plugin #2070

Merged
merged 3 commits into from
Dec 18, 2023
Merged

Fixes and docs for usage as plugin #2070

merged 3 commits into from
Dec 18, 2023

Conversation

nirs
Copy link
Contributor

@nirs nirs commented Nov 12, 2023 •
edited

Using the new CommandDisplayNameAnnotation annotation introduced in Cobra 1.8.0.

Fixes help text issues with:

  • help flag usage
  • help command long description
  • usage line for command without sub commands

@nirs nirs mentioned this pull request Nov 12, 2023
Merged
nirs
nirs commented Nov 12, 2023
View reviewed changes
site/content/user_guide.md Outdated Show resolved Hide resolved
@nirs
Fix help text for plugins
87f8a10 
When using `CommandDisplayNameAnnotation` we want to use it instead of
the command name in `--help` message or in the default help command.

With current code we get the wrong text in the --help usage text:

    Flags:
      -h, --help   help for kubectl-plugin

And in the long description of the default help command:

    $ kubectl cobraplugin help -h
    Help provides help for any command in the application.
    Simply type kubectl-plugin help [path to command] for full details.

The issue was hidden since the test checked only the Usage line.

Fixed by extracting a displayName() function and use it when creating
FlagSet and when formatting the default help flag usage and the help
command long description.

Enhance the TestPlugin to check all the lines including the command
name.
nirs added a commit to nirs/kubectl-cobraplugin that referenced this pull request Nov 12, 2023
@nirs
Use again local cobra
b96f30f 
Required for --help message and help command fixes[1]

[1] spf13/cobra#2070)
@nirs
Copy link
Contributor Author

nirs commented Nov 12, 2023

Example runs using https://github.com/nirs/kubectl-cobraplugin

Root command help:

$ kubectl cobraplugin
Usage:
  kubectl cobraplugin [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  subcmd      

Flags:
  -h, --help   help for kubectl cobraplugin

Use "kubectl cobraplugin [command] --help" for more information about a command.

Sub command help:

$ kubectl cobraplugin subcmd -h
Usage:
  kubectl cobraplugin subcmd [flags]

Flags:
  -h, --help   help for subcmd

Help command help:

$ kubectl cobraplugin help -h
Help provides help for any command in the application.
Simply type kubectl cobraplugin help [path to command] for full details.

Usage:
  kubectl cobraplugin help [command] [flags]

Flags:
  -h, --help   help for help

@nirs nirs changed the title Document how to create a plugin Fixes and docs for usage as plugin Nov 12, 2023
nirs added a commit to nirs/kubernetes that referenced this pull request Nov 12, 2023
@nirs
Fix kubectl-ns plugin help text
ec1c21e 
The plugin help text was not consistent - using `ns` in some cases and
`kubectl ns` in others:

    $ ./kubectl-ns -h
    ...
    Usage:
      ns [new-namespace] [flags]

    Examples:

            # view the current namespace in your KUBECONFIG
            kubectl ns

            ...

    Flags:
      -h, --help                           help for ns
      ...

With cobra 1.8.1 we can fix the issue by annotating the command so the
help text matches the way we use the command. With this change we can
use the executable name (kubectl-ns) as the `Use` argument, and have
`kubectl ns` in the help text.

Issues:
- Requires Cobra release including spf13/cobra#2070
- Tested using local cobra with the require fix.
@nirs
Fix help text for runnable plugin command
e368063 
When creating a plugin without sub commands, the help text included the
command name (kubectl-plugin) instead of the display name (kubectl plugin):

    Usage:
      kubectl-plugin [flags]

The issue is that the usage line for this case does not use the
command path but the raw `Use` string, and this case was not tested.

Add a test for this case and fix UsageLine() to replace the command name
with the display name.

Tested using https://github.com/nirs/kubernetes/tree/sample-cli-plugin-help
@nirs
Document how to create a plugin
e00551d 
Using the new CommandDisplayNameAnnotation annotation introduced in
Cobra 1.8.0.
@nirs
Copy link
Contributor Author

nirs commented Nov 12, 2023

Examples run with sample-cli-plugin:
https://github.com/nirs/kubernetes/tree/sample-cli-plugin-help

$ kubectl ns -h
View or set the current namespace

Usage:
  kubectl ns [new-namespace] [flags]

Examples:

	# view the current namespace in your KUBECONFIG
	kubectl ns

	# view all of the namespaces in use by contexts in your KUBECONFIG
	kubectl ns --list

	# switch your current-context to one that contains the desired namespace
	kubectl ns foo


Flags:
  -h, --help                           help for kubectl ns
  ...

@nirs
Copy link
Contributor Author

nirs commented Dec 2, 2023

@jpmcb @marckhouzam did you have time to look at it?

@marckhouzam marckhouzam added this to the 1.9.0 milestone Dec 18, 2023
@marckhouzam marckhouzam added kind/bug A bug in cobra; unintended behavior area/cobra-command Core `cobra.Command` implementations area/flags-args Changes to functionality around command line flags and args labels Dec 18, 2023
marckhouzam
marckhouzam approved these changes Dec 18, 2023
View reviewed changes
Copy link
Collaborator

@marckhouzam marckhouzam left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for following-up on these issues @nirs !
LGTM

@marckhouzam marckhouzam merged commit 4122785 into spf13:main Dec 18, 2023
16 checks passed
@nirs nirs deleted the plugin-docs branch January 2, 2024 16:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@marckhouzam marckhouzam marckhouzam approved these changes

Assignees
No one assigned
Labels
area/cobra-command Core `cobra.Command` implementations area/flags-args Changes to functionality around command line flags and args kind/bug A bug in cobra; unintended behavior
Projects
None yet
Milestone
1.9.0
Development

Successfully merging this pull request may close these issues.

None yet
2 participants
@nirs @marckhouzam