diff --git a/site/content/CHANGELOG.md b/site/content/changelog.md similarity index 95% rename from site/content/CHANGELOG.md rename to site/content/changelog.md index 742d6d6e24..da84dc3e9b 100644 --- a/site/content/CHANGELOG.md +++ b/site/content/changelog.md @@ -1,11 +1,19 @@ +--- +weight: 31 +--- + # Cobra Changelog ## Pending + * Fix man page doc generation - no auto generated tag when `cmd.DisableAutoGenTag = true` @jpmcb ## v1.0.0 + Announcing v1.0.0 of Cobra. 🎉 -**Notable Changes** + +### Notable Changes + * Fish completion (including support for Go custom completion) @marckhouzam * API (urgent): Rename BashCompDirectives to ShellCompDirectives @marckhouzam * Remove/replace SetOutput on Command - deprecated @jpmcb diff --git a/site/content/bash_completions.md b/site/content/completions/bash.md similarity index 97% rename from site/content/bash_completions.md rename to site/content/completions/bash.md index a82d5bb8b4..913a7c5a78 100644 --- a/site/content/bash_completions.md +++ b/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 backwards-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. diff --git a/site/content/fish_completions.md b/site/content/completions/fish.md similarity index 57% rename from site/content/fish_completions.md rename to site/content/completions/fish.md index 19b2ed1293..9bbce1ac8a 100644 --- a/site/content/fish_completions.md +++ b/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. diff --git a/site/content/powershell_completions.md b/site/content/completions/powershell.md similarity index 90% rename from site/content/powershell_completions.md rename to site/content/completions/powershell.md index 55f154a68f..5bdec1a174 100644 --- a/site/content/powershell_completions.md +++ b/site/content/completions/powershell.md @@ -1,15 +1,19 @@ -# Generating PowerShell Completions For Your Own cobra.Command +--- +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 +### 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 +### What's not yet supported - Command aliases - Required, filename or custom flags (they will work like normal flags) diff --git a/site/content/shell_completions.md b/site/content/completions/shell.md similarity index 96% rename from site/content/shell_completions.md rename to site/content/completions/shell.md index d8416ab1dc..81e860b116 100644 --- a/site/content/shell_completions.md +++ b/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: @@ -70,13 +74,13 @@ $ yourprogram completion fish > ~/.config/fish/completions/yourprogram.fish **Note:** The cobra generator may include messages printed to stdout for example if the config file is loaded, this will break the auto complete script so must be removed. -# 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. @@ -105,7 +109,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`: @@ -130,7 +134,7 @@ backend frontend database Note that without declaring `rc` as an alias, the completion algorithm would not know to show the list of replication controllers following `rc`. -### 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: @@ -198,7 +202,7 @@ ShellCompDirectiveFilterDirs ***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 @@ -231,9 +235,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: @@ -249,7 +253,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. @@ -266,7 +270,7 @@ $ helm status --output [tab][tab] json table yaml ``` -#### Debugging +##### Debugging You can also easily debug your Go completion code for flags: ```bash @@ -279,7 +283,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 @@ -293,7 +297,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 @@ -314,7 +318,7 @@ cmd.RegisterFlagCompletionFunc(flagName, func(cmd *cobra.Command, args []string, return []string{"themes"}, cobra.ShellCompDirectiveFilterDirs }) ``` -### Descriptions for completions +#### Descriptions for completions Both `zsh` and `fish` allow for descriptions to annotate completion choices. For commands and flags, Cobra will provide the descriptions automatically, based on usage information. For example, using zsh: ``` @@ -339,13 +343,13 @@ or ```go ValidArgs: []string{"bash\tCompletions for bash", "zsh\tCompletions for zsh"} ``` -## Bash completions +### Bash -### Dependencies +#### 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. @@ -359,12 +363,12 @@ complete -o default -F __start_origcommand aliasname $ aliasname completion firstcommand secondcommand ``` -### Bash legacy dynamic completions +#### Bash legacy dynamic completions For backwards-compatibility, Cobra still supports its bash legacy dynamic completion solution. Please refer to [Bash Completions](bash_completions.md) for details. -## Zsh completions +### 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 @@ -387,19 +391,19 @@ search show status ``` *Note*: Because of backwards-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`). * 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 backwards-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. ``` @@ -413,7 +417,7 @@ search show status ``` *Note*: Because of backwards-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`). @@ -429,6 +433,6 @@ search show status * `ShellCompDirectiveFilterFileExt` (filtering by file extension) * `ShellCompDirectiveFilterDirs` (filtering by directory) -## PowerShell completions +### PowerShell Please refer to [PowerShell Completions](powershell_completions.md) for details. diff --git a/site/content/zsh_completions.md b/site/content/completions/zsh.md similarity index 94% rename from site/content/zsh_completions.md rename to site/content/completions/zsh.md index 7cff61787f..b30c2751c2 100644 --- a/site/content/zsh_completions.md +++ b/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 diff --git a/site/content/CONTRIBUTING.md b/site/content/contributing.md similarity index 99% rename from site/content/CONTRIBUTING.md rename to site/content/contributing.md index 6f356e6a82..b31fc7e558 100644 --- a/site/content/CONTRIBUTING.md +++ b/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. diff --git a/site/content/docgen/README.md b/site/content/docgen/README.md deleted file mode 100644 index 6ea4eb6623..0000000000 --- a/site/content/docgen/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# Documentation generation - -- [Man page docs](./man_docs.md) -- [Markdown docs](./md_docs.md) -- [Rest docs](./rest_docs.md) -- [Yaml docs](./yaml_docs.md) - -## Options -### `DisableAutoGenTag` -You may set `cmd.DisableAutoGenTag = true` -to _entirely_ remove the auto generated string "Auto generated by spf13/cobra..." -from any documentation source. diff --git a/site/content/docgen/docgen.md b/site/content/docgen/docgen.md new file mode 100644 index 0000000000..5679c38a45 --- /dev/null +++ b/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. diff --git a/site/content/docgen/man_docs.md b/site/content/docgen/man_docs.md index 3709160f34..6a9e1f0390 100644 --- a/site/content/docgen/man_docs.md +++ b/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: diff --git a/site/content/docgen/md_docs.md b/site/content/docgen/md_docs.md index 5c870625f7..7237892e61 100644 --- a/site/content/docgen/md_docs.md +++ b/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: diff --git a/site/content/docgen/rest_docs.md b/site/content/docgen/rest_docs.md index 6098430eff..b4f2b97836 100644 --- a/site/content/docgen/rest_docs.md +++ b/site/content/docgen/rest_docs.md @@ -1,4 +1,8 @@ -# Generating ReStructured Text Docs For Your Own cobra.Command +--- +weight: 23 +--- + +## ReStructured Text Docs Generating ReST pages from a cobra command is incredibly easy. An example is as follows: @@ -26,7 +30,7 @@ func main() { That will get you a ReST document `/tmp/test.rst` -## Generate ReST 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 ReST 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 `GenReST` instead of `GenReSTTree` @@ -69,7 +73,7 @@ You may wish to have more control over the output, or only generate for a single This will write the ReST doc for ONLY "cmd" into the out, buffer. -## Customize the output +### Customize the output Both `GenReST` and `GenReSTTree` have alternate versions with callbacks to get some control of the output: diff --git a/site/content/docgen/yaml_docs.md b/site/content/docgen/yaml_docs.md index 1a9b7c6a3c..2c5995221d 100644 --- a/site/content/docgen/yaml_docs.md +++ b/site/content/docgen/yaml_docs.md @@ -1,4 +1,8 @@ -# Generating Yaml Docs For Your Own cobra.Command +--- +weight: 24 +--- + +## Yaml Docs Generating yaml files from a cobra command is incredibly easy. An example is as follows: @@ -26,7 +30,7 @@ func main() { That will get you a Yaml document `/tmp/test.yaml` -## Generate yaml 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 yaml 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 `GenYaml` instead of `GenYamlTree` @@ -66,7 +70,7 @@ You may wish to have more control over the output, or only generate for a single This will write the yaml doc for ONLY "cmd" into the out, buffer. -## Customize the output +### Customize the output Both `GenYaml` and `GenYamlTree` have alternate versions with callbacks to get some control of the output: diff --git a/site/content/projects_using_cobra.md b/site/content/projects_using_cobra.md index 31c272036a..cb2234ad04 100644 --- a/site/content/projects_using_cobra.md +++ b/site/content/projects_using_cobra.md @@ -1,4 +1,8 @@ -## Projects using Cobra +--- +weight: 32 +--- + +# Projects using Cobra - [Arduino CLI](https://github.com/arduino/arduino-cli) - [Bleve](http://www.blevesearch.com/) diff --git a/site/static/images/logo.png b/site/static/images/logo.png new file mode 100644 index 0000000000..a6174acc8a Binary files /dev/null and b/site/static/images/logo.png differ