Merge pull request kubernetes#34502 from fabianofranz/cli_usability_i…

…mprovements

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

kubectl-conventions.md

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