From a8ba6f93d92292a1a60fca1686a2c4c6c9563d2f Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 12 Sep 2017 11:02:51 +0200 Subject: [PATCH 1/2] 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 --- docs/yaml/yaml.go | 48 ++++++++++++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 19 deletions(-) diff --git a/docs/yaml/yaml.go b/docs/yaml/yaml.go index edf5e9dd7f..10e2f61c6b 100644 --- a/docs/yaml/yaml.go +++ b/docs/yaml/yaml.go @@ -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 From 1f48e75c5c1d270610115edfd8742691188d881f Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 12 Sep 2017 11:24:45 +0200 Subject: [PATCH 2/2] Add more information about commands to generated YAML docs This patch adds aditional information about commands to the YAML files that are generated for the reference documentation. The following fields are added for each command: Property | Type | Description ------------------|-----------|--------------------------------------------------------------------------------------- deprecated | Boolean | Indicates if the command is marked deprecated min_api_version | String | The API version required to use this command (e.g. "1.23") experimental | Boolean | Indicates if the command requires the daemon to run with experimental features enabled For example (taken from the experimental `docker checkpoint create` command): command: docker checkpoint create short: Create a checkpoint from a running container long: Create a checkpoint from a running container usage: docker checkpoint create [OPTIONS] CONTAINER CHECKPOINT pname: docker checkpoint plink: docker_checkpoint.yaml options: - option: checkpoint-dir value_type: string description: Use a custom checkpoint storage directory deprecated: false experimental: false - option: leave-running value_type: bool default_value: "false" description: Leave the container running after checkpoint deprecated: false experimental: false deprecated: false min_api_version: "1.25" experimental: true Signed-off-by: Sebastiaan van Stijn --- docs/yaml/yaml.go | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/docs/yaml/yaml.go b/docs/yaml/yaml.go index 10e2f61c6b..2dbe406bdb 100644 --- a/docs/yaml/yaml.go +++ b/docs/yaml/yaml.go @@ -39,6 +39,9 @@ type cmdDoc struct { Options []cmdOption `yaml:",omitempty"` InheritedOptions []cmdOption `yaml:"inherited_options,omitempty"` Example string `yaml:"examples,omitempty"` + Deprecated bool + MinAPIVersion string `yaml:"min_api_version,omitempty"` + Experimental bool } // GenYamlTree creates yaml structured ref files @@ -77,12 +80,11 @@ func GenYamlTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandle } // GenYamlCustom creates custom yaml output +// nolint: gocyclo func GenYamlCustom(cmd *cobra.Command, w io.Writer) error { cliDoc := cmdDoc{} cliDoc.Name = cmd.CommandPath() - // Check experimental: ok := cmd.Tags["experimental"] - cliDoc.Aliases = strings.Join(cmd.Aliases, ", ") cliDoc.Short = cmd.Short cliDoc.Long = cmd.Long @@ -97,6 +99,18 @@ func GenYamlCustom(cmd *cobra.Command, w io.Writer) error { if len(cmd.Example) > 0 { cliDoc.Example = cmd.Example } + if len(cmd.Deprecated) > 0 { + cliDoc.Deprecated = true + } + // Check recursively so that, e.g., `docker stack ls` returns the same output as `docker stack` + for curr := cmd; curr != nil; curr = curr.Parent() { + if v, ok := curr.Tags["version"]; ok && cliDoc.MinAPIVersion == "" { + cliDoc.MinAPIVersion = v + } + if _, ok := curr.Tags["experimental"]; ok && !cliDoc.Experimental { + cliDoc.Experimental = true + } + } flags := cmd.NonInheritedFlags() if flags.HasFlags() {