site: rework structure and headers

site/content/bash_completions.md → site/content/completions/bash.md

@@ -1,8 +1,12 @@
-# Generating Bash Completions For Your cobra.Command
+---
+weight: 11
+---
+
+## Bash completions
 
 Please refer to [Shell Completions](shell_completions.md) for details.
 
-## Bash legacy dynamic completions
+### Bash legacy dynamic completions
 
 For backward compatibility, Cobra still supports its legacy dynamic completion solution (described below).  Unlike the `ValidArgsFunction` solution, the legacy solution will only work for Bash shell-completion and not for other shells. This legacy solution can be used along-side `ValidArgsFunction` and `RegisterFlagCompletionFunc()`, as long as both solutions are not used for the same command.  This provides a path to gradually migrate from the legacy solution to the new solution.
 

site/content/fish_completions.md → site/content/completions/fish.md

@@ -1,4 +1,8 @@
-## Generating Fish Completions For Your cobra.Command
+---
+weight: 12
+---
+
+## Fish completions
 
 Please refer to [Shell Completions](shell_completions.md) for details.
 

site/content/completions/powershell.md

@@ -0,0 +1,20 @@
+---
+weight: 13
+---
+
+## PowerShell completions
+
+Cobra can generate PowerShell completion scripts. Users need PowerShell version 5.0 or above, which comes with Windows 10 and can be downloaded separately for Windows 7 or 8.1. They can then write the completions to a file and source this file from their PowerShell profile, which is referenced by the `$Profile` environment variable. See `Get-Help about_Profiles` for more info about PowerShell profiles.
+
+*Note*: PowerShell completions have not (yet?) been aligned to Cobra's generic shell completion support.  This implies the PowerShell completions are not as rich as for other shells (see [What's not yet supported](#whats-not-yet-supported)), and may behave slightly differently.  They are still very useful for PowerShell users.
+
+### What's supported
+
+- Completion for subcommands using their `.Short` description
+- Completion for non-hidden flags using their `.Name` and `.Shorthand`
+
+### What's not yet supported
+
+- Command aliases
+- Required, filename or custom flags (they will work like normal flags)
+- Custom completion scripts

site/content/shell_completions.md → site/content/completions/shell.md

@@ -1,4 +1,8 @@
-# Generating shell completions
+---
+weight: 10
+---
+
+# Shell completions
 
 Cobra can generate shell completions for multiple shells.
 The currently supported shells are:
@@ -114,13 +118,13 @@ To tell Cobra to completely disable descriptions for completions:
 rootCmd.CompletionOptions.DisableDescriptions = true
 ```
 
-# Customizing completions
+## Customizing completions
 
 The generated completion scripts will automatically handle completing commands and flags.  However, you can make your completions much more powerful by providing information to complete your program's nouns and flag values.
 
-## Completion of nouns
+### Completion of nouns
 
-### Static completion of nouns
+#### Static completion of nouns
 
 Cobra allows you to provide a pre-defined list of completion choices for your nouns using the `ValidArgs` field.
 For example, if you want `kubectl get [tab][tab]` to show a list of valid "nouns" you have to set them.
@@ -148,7 +152,7 @@ $ kubectl get [tab][tab]
 node   pod   replicationcontroller   service
 ```
 
-#### Aliases for nouns
+##### Aliases for nouns
 
 If your nouns have aliases, you can define them alongside `ValidArgs` using `ArgAliases`:
 
@@ -164,7 +168,7 @@ cmd := &cobra.Command{
 
 The aliases are shown to the user on tab completion only if no completions were found within sub-commands or `ValidArgs`.
 
-### Dynamic completion of nouns
+#### Dynamic completion of nouns
 
 In some cases it is not possible to provide a list of completions in advance.  Instead, the list of completions must be determined at execution-time. In a similar fashion as for static completions, you can use the `ValidArgsFunction` field to provide a Go function that Cobra will execute when it needs the list of completion choices for the nouns of a command.  Note that either `ValidArgs` or `ValidArgsFunction` can be used for a single cobra command, but not both.
 Simplified code from `helm status` looks like:
@@ -236,7 +240,7 @@ ShellCompDirectiveKeepOrder
 
 ***Note***: When using the `ValidArgsFunction`, Cobra will call your registered function after having parsed all flags and arguments provided in the command-line.  You therefore don't need to do this parsing yourself.  For example, when a user calls `helm status --namespace my-rook-ns [tab][tab]`, Cobra will call your registered `ValidArgsFunction` after having parsed the `--namespace` flag, as it would have done when calling the `RunE` function.
 
-#### Debugging
+##### Debugging
 
 Cobra achieves dynamic completion through the use of a hidden command called by the completion script.  To debug your Go completion code, you can call this hidden command directly:
 ```bash
@@ -269,9 +273,9 @@ cobra.CompErrorln(msg string)
 ```
 ***Important:*** You should **not** leave traces that print directly to stdout in your completion code as they will be interpreted as completion choices by the completion script.  Instead, use the cobra-provided debugging traces functions mentioned above.
 
-## Completions for flags
+### Completions for flags
 
-### Mark flags as required
+#### Mark flags as required
 
 Most of the time completions will only show sub-commands. But if a flag is required to make a sub-command work, you probably want it to show up when the user types [tab][tab].  You can mark a flag as 'Required' like so:
 
@@ -287,7 +291,7 @@ $ kubectl exec [tab][tab]
 -c            --container=  -p            --pod=
 ```
 
-### Specify dynamic flag completion
+#### Specify dynamic flag completion
 
 As for nouns, Cobra provides a way of defining dynamic completion of flags.  To provide a Go function that Cobra will execute when it needs the list of completion choices for a flag, you must register the function using the `command.RegisterFlagCompletionFunc()` function.
 
@@ -304,7 +308,7 @@ $ helm status --output [tab][tab]
 json table yaml
 ```
 
-#### Debugging
+##### Debugging
 
 You can also easily debug your Go completion code for flags:
 ```bash
@@ -317,7 +321,7 @@ Completion ended with directive: ShellCompDirectiveNoFileComp # This is on stder
 ```
 ***Important:*** You should **not** leave traces that print to stdout in your completion code as they will be interpreted as completion choices by the completion script.  Instead, use the cobra-provided debugging traces functions mentioned further above.
 
-### Specify valid filename extensions for flags that take a filename
+#### Specify valid filename extensions for flags that take a filename
 
 To limit completions of flag values to file names with certain extensions you can either use the different `MarkFlagFilename()` functions or a combination of `RegisterFlagCompletionFunc()` and `ShellCompDirectiveFilterFileExt`, like so:
 ```go
@@ -331,7 +335,7 @@ cmd.RegisterFlagCompletionFunc(flagName, func(cmd *cobra.Command, args []string,
 	return []string{"yaml", "json"}, ShellCompDirectiveFilterFileExt})
 ```
 
-### Limit flag completions to directory names
+#### Limit flag completions to directory names
 
 To limit completions of flag values to directory names you can either use the `MarkFlagDirname()` functions or a combination of `RegisterFlagCompletionFunc()` and `ShellCompDirectiveFilterDirs`, like so:
 ```go
@@ -352,7 +356,7 @@ cmd.RegisterFlagCompletionFunc(flagName, func(cmd *cobra.Command, args []string,
 	return []string{"themes"}, cobra.ShellCompDirectiveFilterDirs
 })
 ```
-### Descriptions for completions
+#### Descriptions for completions
 
 Cobra provides support for completion descriptions.  Such descriptions are supported for each shell
 (however, for bash, it is only available in the [completion V2 version](#bash-completion-v2)).
@@ -393,13 +397,14 @@ $ source <(helm completion bash --no-descriptions)
 $ helm completion [tab][tab]
 bash        fish        powershell  zsh
 ```
-## Bash completions
 
-### Dependencies
+### Bash
+
+#### Dependencies
 
 The bash completion script generated by Cobra requires the `bash_completion` package. You should update the help text of your completion command to show how to install the `bash_completion` package ([Kubectl docs](https://kubernetes.io/docs/tasks/tools/install-kubectl/#enabling-shell-autocompletion))
 
-### Aliases
+#### Aliases
 
 You can also configure `bash` aliases for your program and they will also support completions.
 
@@ -413,7 +418,7 @@ complete -o default -F __start_origcommand aliasname
 $ aliasname <tab><tab>
 completion     firstcommand   secondcommand
 ```
-### Bash legacy dynamic completions
+#### Bash legacy dynamic completions
 
 For backward compatibility, Cobra still supports its bash legacy dynamic completion solution.
 Please refer to [Bash Completions](bash_completions.md) for details.
@@ -431,7 +436,7 @@ Unless your program already uses the legacy dynamic completion solution, it is r
 completion V2 solution which provides the following extra features:
 - Supports completion descriptions (like the other shells)
 - Small completion script of less than 300 lines (v1 generates scripts of thousands of lines; `kubectl` for example has a bash v1 completion script of over 13K lines)
-- Streamlined user experience thanks to a completion behavior aligned with the other shells 
+- Streamlined user experience thanks to a completion behavior aligned with the other shells
 
 `Bash` completion V2 supports descriptions for completions. When calling `GenBashCompletionV2()` or `GenBashCompletionFileV2()`
 you must provide these functions with a parameter indicating if the completions should be annotated with a description; Cobra
@@ -448,8 +453,9 @@ show    (show information of a chart)
 $ helm s[tab][tab]
 search  show  status
 ```
-**Note**: Cobra's default `completion` command uses bash completion V2.  If for some reason you need to use bash completion V1, you will need to implement your own `completion` command. 
-## Zsh completions
+**Note**: Cobra's default `completion` command uses bash completion V2.  If for some reason you need to use bash completion V1, you will need to implement your own `completion` command.
+
+### Zsh
 
 Cobra supports native zsh completion generated from the root `cobra.Command`.
 The generated completion script should be put somewhere in your `$fpath` and be named
@@ -472,19 +478,19 @@ search  show  status
 ```
 *Note*: Because of backward-compatibility requirements, we were forced to have a different API to disable completion descriptions between `zsh` and `fish`.
 
-### Limitations
+#### Limitations
 
 * Custom completions implemented in Bash scripting (legacy) are not supported and will be ignored for `zsh` (including the use of the `BashCompCustom` flag annotation).
   * You should instead use `ValidArgsFunction` and `RegisterFlagCompletionFunc()` which are portable to the different shells (`bash`, `zsh`, `fish`, `powershell`).
 * The function `MarkFlagCustom()` is not supported and will be ignored for `zsh`.
   * You should instead use `RegisterFlagCompletionFunc()`.
 
-### Zsh completions standardization
+#### Zsh completions standardization
 
 Cobra 1.1 standardized its zsh completion support to align it with its other shell completions.  Although the API was kept backward-compatible, some small changes in behavior were introduced.
 Please refer to [Zsh Completions](zsh_completions.md) for details.
 
-## fish completions
+### Fish
 
 Cobra supports native fish completions generated from the root `cobra.Command`.  You can use the `command.GenFishCompletion()` or `command.GenFishCompletionFile()` functions. You must provide these functions with a parameter indicating if the completions should be annotated with a description; Cobra will provide the description automatically based on usage information.  You can choose to make this option configurable by your users.
 ```
@@ -498,7 +504,7 @@ search  show  status
 ```
 *Note*: Because of backward-compatibility requirements, we were forced to have a different API to disable completion descriptions between `zsh` and `fish`.
 
-### Limitations
+#### Limitations
 
 * Custom completions implemented in bash scripting (legacy) are not supported and will be ignored for `fish` (including the use of the `BashCompCustom` flag annotation).
   * You should instead use `ValidArgsFunction` and `RegisterFlagCompletionFunc()` which are portable to the different shells (`bash`, `zsh`, `fish`, `powershell`).
@@ -514,7 +520,7 @@ search  show  status
   * `ShellCompDirectiveFilterFileExt` (filtering by file extension)
   * `ShellCompDirectiveFilterDirs` (filtering by directory)
 
-## PowerShell completions
+### PowerShell
 
 Cobra supports native PowerShell completions generated from the root `cobra.Command`. You can use the `command.GenPowerShellCompletion()` or `command.GenPowerShellCompletionFile()` functions. To include descriptions use `command.GenPowerShellCompletionWithDesc()` and `command.GenPowerShellCompletionFileWithDesc()`. Cobra will provide the description automatically based on usage information. You can choose to make this option configurable by your users.
 
@@ -535,7 +541,7 @@ search  (search for a keyword in charts)  show  (show information of a chart)  s
 
 # With descriptions and Mode 'MenuComplete' The description of the current selected value will be displayed below the suggestions.
 $ helm s[tab]
-search    show     status  
+search    show     status
 
 search for a keyword in charts
 

site/content/zsh_completions.md → site/content/completions/zsh.md

@@ -1,12 +1,16 @@
-## Generating Zsh Completion For Your cobra.Command
+---
+weight: 14
+---
+
+## Zsh completions
 
 Please refer to [Shell Completions](shell_completions.md) for details.
 
-## Zsh completions standardization
+### Zsh completions standardization
 
 Cobra 1.1 standardized its zsh completion support to align it with its other shell completions.  Although the API was kept backwards-compatible, some small changes in behavior were introduced.
 
-### Deprecation summary
+#### Deprecation summary
 
 See further below for more details on these deprecations.
 
@@ -16,9 +20,10 @@ See further below for more details on these deprecations.
 * `cmd.MarkZshCompPositionalArgumentWords()` is **deprecated** and silently ignored.
   * Instead use `ValidArgsFunction`.
 
-### Behavioral changes
+#### Behavioral changes
+
+##### Noun completion*
 
-**Noun completion**
 |Old behavior|New behavior|
 |---|---|
 |No file completion by default (opposite of bash)|File completion by default; use `ValidArgsFunction` with `ShellCompDirectiveNoFileComp` to turn off file completion on a per-argument basis|
@@ -27,7 +32,7 @@ See further below for more details on these deprecations.
 |`cmd.MarkZshCompPositionalArgumentFile(pos, glob[])` used to turn on file completion **with glob filtering** on a per-argument position basis (zsh-specific)|`cmd.MarkZshCompPositionalArgumentFile()` is **deprecated** and silently ignored; use `ValidArgsFunction` with `ShellCompDirectiveFilterFileExt` for file **extension** filtering (not full glob filtering)|
 |`cmd.MarkZshCompPositionalArgumentWords(pos, words[])` used to provide completion choices on a per-argument position basis (zsh-specific)|`cmd.MarkZshCompPositionalArgumentWords()` is **deprecated** and silently ignored; use `ValidArgsFunction` to achieve the same behavior|
 
-**Flag-value completion**
+##### Flag-value completion
 
 |Old behavior|New behavior|
 |---|---|
@@ -38,7 +43,7 @@ See further below for more details on these deprecations.
 |Completion of a flag name does not repeat, unless flag is of type `*Array` or `*Slice` (not supported by bash)|Retained for `zsh` and added to `fish`|
 |Completion of a flag name does not provide the `=` form (unlike bash)|Retained for `zsh` and added to `fish`|
 
-**Improvements**
+##### Improvements
 
 * Custom completion support (`ValidArgsFunction` and `RegisterFlagCompletionFunc()`)
 * File completion by default if no other completions found

site/content/CONTRIBUTING.md → site/content/contributing.md

@@ -1,3 +1,7 @@
+---
+weight: 30
+---
+
 # Contributing to Cobra
 
 Thank you so much for contributing to Cobra. We appreciate your time and help.

site/content/docgen/docgen.md

@@ -0,0 +1,9 @@
+---
+weight: 20
+---
+
+# Documentation generation
+
+## Options
+
+- `DisableAutoGenTag`. You may set `cmd.DisableAutoGenTag = true` to _entirely_ remove the auto generated string "*Auto generated by spf13/cobra...*" from any documentation source.

site/content/docgen/man_docs.md

@@ -1,4 +1,8 @@
-# Generating Man Pages For Your Own cobra.Command
+---
+weight: 21
+---
+
+## Man Pages
 
 Generating man pages from a cobra command is incredibly easy. An example is as follows:
 

site/content/docgen/md_docs.md

@@ -1,4 +1,8 @@
-# Generating Markdown Docs For Your Own cobra.Command
+---
+weight: 22
+---
+
+## Markdown Docs
 
 Generating Markdown pages from a cobra command is incredibly easy. An example is as follows:
 
@@ -26,7 +30,7 @@ func main() {
 
 That will get you a Markdown document `/tmp/test.md`
 
-## Generate markdown docs for the entire command tree
+### The entire command tree
 
 This program can actually generate docs for the kubectl command in the kubernetes project
 
@@ -55,7 +59,7 @@ func main() {
 
 This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./")
 
-## Generate markdown docs for a single command
+### For a single command
 
 You may wish to have more control over the output, or only generate for a single command, instead of the entire command tree. If this is the case you may prefer to `GenMarkdown` instead of `GenMarkdownTree`
 
@@ -69,7 +73,7 @@ You may wish to have more control over the output, or only generate for a single
 
 This will write the markdown doc for ONLY "cmd" into the out, buffer.
 
-## Customize the output
+### Customize the output
 
 Both `GenMarkdown` and `GenMarkdownTree` have alternate versions with callbacks to get some control of the output: