q3k
/
docker-cli-openbsd
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add more information about command flags to generated YAML docs 

This patch adds aditional information about command flags to the YAML files
that are generated for the reference documentation.

The following fields are added for each flag:

Property          | Type      | Description
------------------|-----------|---------------------------------------------------------------------------------------
value_type        | String    | The "type" of value to be passed to this flag (e.g., `uint64`, `list`)
deprecated        | Boolean   | Indicates if the flag is marked deprecated
min_api_version   | String    | The API version required to use this flag (e.g. "1.23")
experimental      | Boolean   | Indicates if the flag requires the daemon to run with experimental features enabled

For example (taken from the `docker image build` command):

    - option: security-opt
      value_type: stringSlice
      default_value: '[]'
      description: Security options
      deprecated: false
      experimental: false
    - option: shm-size
      value_type: bytes
      default_value: "0"
      description: Size of /dev/shm
      deprecated: false
      experimental: false
    - option: squash
      value_type: bool
      default_value: "false"
      description: Squash newly built layers into a single new layer
      deprecated: false
      min_api_version: "1.25"
      experimental: true

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
master
Sebastiaan van Stijn 2017-09-12 11:02:51 +02:00
parent 7b77ab5c60
commit a8ba6f93d9
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
1 changed files with 29 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/yaml/yaml.go
View File

@ -14,10 +14,14 @@ import (
)
type cmdOption struct {
Option string
Shorthand string `yaml:",omitempty"`
DefaultValue string `yaml:"default_value,omitempty"`
Description string `yaml:",omitempty"`
Option string
Shorthand string `yaml:",omitempty"`
ValueType string `yaml:"value_type,omitempty"`
DefaultValue string `yaml:"default_value,omitempty"`
Description string `yaml:",omitempty"`
Deprecated bool
MinAPIVersion string `yaml:"min_api_version,omitempty"`
Experimental bool
}
type cmdDoc struct {
@ -142,28 +146,34 @@ func GenYamlCustom(cmd *cobra.Command, w io.Writer) error {
}
func genFlagResult(flags *pflag.FlagSet) []cmdOption {
var result []cmdOption
var (
result []cmdOption
opt cmdOption
)
flags.VisitAll(func(flag *pflag.Flag) {
opt = cmdOption{
Option: flag.Name,
ValueType: flag.Value.Type(),
DefaultValue: forceMultiLine(flag.DefValue),
Description: forceMultiLine(flag.Usage),
Deprecated: len(flag.Deprecated) > 0,
}
// Todo, when we mark a shorthand is deprecated, but specify an empty message.
// The flag.ShorthandDeprecated is empty as the shorthand is deprecated.
// Using len(flag.ShorthandDeprecated) > 0 can't handle this, others are ok.
if !(len(flag.ShorthandDeprecated) > 0) && len(flag.Shorthand) > 0 {
opt := cmdOption{
Option: flag.Name,
Shorthand: flag.Shorthand,
DefaultValue: flag.DefValue,
Description: forceMultiLine(flag.Usage),
}
result = append(result, opt)
} else {
opt := cmdOption{
Option: flag.Name,
DefaultValue: forceMultiLine(flag.DefValue),
Description: forceMultiLine(flag.Usage),
}
result = append(result, opt)
opt.Shorthand = flag.Shorthand
}
if _, ok := flag.Annotations["experimental"]; ok {
opt.Experimental = true
}
if v, ok := flag.Annotations["version"]; ok {
opt.MinAPIVersion = v[0]
}
result = append(result, opt)
})
return result