From be035a0272fac8416848934ca4be6d8869d91cae Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Wed, 30 May 2018 23:17:06 +0200
Subject: [PATCH] YAML docs: add os_type property on flags and (sub)commands

This patch adds an `os_type` property in the generated YAML docs, both for
commands, and for flags;

Note that the ostype annotation on flags can have multiple values set,
however, multiple values are currently not used (and unlikely will).

To simplify usage of the os_type property in the YAML, and for consistency with
the same property for commands, we're only using the first ostype that's set.

```yaml
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 [flags]
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
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: leave-running
  value_type: bool
  default_value: "false"
  description: Leave the container running after checkpoint
  deprecated: false
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
deprecated: false
min_api_version: "1.25"
experimental: true
experimentalcli: false
kubernetes: false
swarm: false
os_type: windows
```

```yaml
command: docker container start
short: Start one or more stopped containers
long: Start one or more stopped containers
usage: docker container start [OPTIONS] CONTAINER [CONTAINER...] [flags]
pname: docker container
plink: docker_container.yaml
options:
- option: attach
  shorthand: a
  value_type: bool
  default_value: "false"
  description: Attach STDOUT/STDERR and forward signals
  deprecated: false
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: checkpoint
  value_type: string
  description: Restore from this checkpoint
  deprecated: false
  experimental: true
  experimentalcli: false
  kubernetes: false
  swarm: false
  os_type: linux
- option: checkpoint-dir
  value_type: string
  description: Use a custom checkpoint storage directory
  deprecated: false
  experimental: true
  experimentalcli: false
  kubernetes: false
  swarm: false
  os_type: linux
- option: detach-keys
  value_type: string
  description: Override the key sequence for detaching a container
  deprecated: false
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: interactive
  shorthand: i
  value_type: bool
  default_value: "false"
  description: Attach container's STDIN
  deprecated: false
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
```

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
---
 docs/yaml/yaml.go | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/yaml/yaml.go b/docs/yaml/yaml.go
index 5dc7164192..82c90973c0 100644
--- a/docs/yaml/yaml.go
+++ b/docs/yaml/yaml.go
@@ -25,6 +25,7 @@ type cmdOption struct {
 	ExperimentalCLI bool
 	Kubernetes      bool
 	Swarm           bool
+	OSType          string `yaml:"os_type,omitempty"`
 }
 
 type cmdDoc struct {
@@ -48,6 +49,7 @@ type cmdDoc struct {
 	ExperimentalCLI  bool
 	Kubernetes       bool
 	Swarm            bool
+	OSType           string `yaml:"os_type,omitempty"`
 }
 
 // GenYamlTree creates yaml structured ref files
@@ -121,6 +123,9 @@ func GenYamlCustom(cmd *cobra.Command, w io.Writer) error {
 		if _, ok := curr.Annotations["swarm"]; ok && !cliDoc.Swarm {
 			cliDoc.Swarm = true
 		}
+		if os, ok := curr.Annotations["ostype"]; ok && cliDoc.OSType == "" {
+			cliDoc.OSType = os
+		}
 	}
 
 	flags := cmd.NonInheritedFlags()
@@ -207,6 +212,15 @@ func genFlagResult(flags *pflag.FlagSet) []cmdOption {
 			opt.Swarm = true
 		}
 
+		// Note that the annotation can have multiple ostypes set, however, multiple
+		// values are currently not used (and unlikely will).
+		//
+		// To simplify usage of the os_type property in the YAML, and for consistency
+		// with the same property for commands, we're only using the first ostype that's set.
+		if ostypes, ok := flag.Annotations["ostype"]; ok && len(opt.OSType) == 0 && len(ostypes) > 0 {
+			opt.OSType = ostypes[0]
+		}
+
 		result = append(result, opt)
 	})