github/kubernetes
1
0
Fork 0
mirror of https://github.com/k3s-io/kubernetes.git synced 2025-09-06 11:42:14 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #34502 from fabianofranz/cli_usability_improvements

Browse Source 
Automatic merge from submit-queue

Improvements to CLI usability and maintainability

Improves `kubectl` from an usability perspective by

1. Fixing how we handle terminal width in help. Some sections like the flags use the entire available width, while others like long descriptions breaks lines but don't follow a well established max width (screenshot below). This PR adds a new responsive writer that will adjust to terminal width and set 80, 100, or 120 columns as the max width, but not more than that given POSIX best practices and recommendations for better readability.
![terminal_width](https://cloud.githubusercontent.com/assets/158611/19253184/b23a983e-8f1f-11e6-9bae-667dd5981485.png)
2. Adds our own normalizers for long descriptions and cmd examples which allows us better control about how things like lists, paragraphs, line breaks, etc are printed. Features markdown support. Looks like `templates.LongDesc` and `templates.Examples` instead of `dedent.Dedend`.
3. Allows simple reordering and reuse of help and usage sections.
3. Adds `verify-cli-conventions.sh` which intends to run tests to make sure cmd developers are using what we propose as [kubectl conventions](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/kubectl-conventions.md). Just a couple simple tests for now but the framework is there and it's easy to extend.
4. Update [kubectl conventions](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/kubectl-conventions.md) to use our own normalizers instead of `dedent.Dedent`.

**Release note**:
<!--  Steps to write your release note:
1. Use the release-note-* labels to set the release note state (if you have access) 
2. Enter your extended release note in the below block; leaving it blank means using the PR title as the release note. If no release note is required, just write `NONE`. 
-->
```release-note
Improves how 'kubectl' uses the terminal size when printing help and usage.
```

@kubernetes/kubectl
This commit is contained in:
Kubernetes Submit Queue
2016-10-17 23:41:23 -07:00
committed by GitHub
parent 3193bedb33 0fd5c8d797
commit c19569f03f
78 changed files with 1654 additions and 599 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/devel/kubectl-conventions.md
View File

@@ -301,24 +301,25 @@ Sample command skeleton:
// MineRecommendedName is the recommended command name for kubectl mine.
const MineRecommendedName = "mine"
// Long command description and examples.
var (
mineLong = templates.LongDesc(`
mine which is described here
with lots of details.`)
mineExample = templates.Examples(`
# Run my command's first action
kubectl mine first_action
# Run my command's second action on latest stuff
kubectl mine second_action --flag`)
)
// MineConfig contains all the options for running the mine cli command.
type MineConfig struct {
mineLatest bool
}
var (
mineLong = dedent.Dedent(`
mine which is described here
with lots of details.`)
mineExample = dedent.Dedent(`
# Run my command's first action
kubectl mine first_action
# Run my command's second action on latest stuff
kubectl mine second_action --flag`)
)
// NewCmdMine implements the kubectl mine command.
func NewCmdMine(parent, name string, f *cmdutil.Factory, out io.Writer) *cobra.Command {
opts := &MineConfig{}