From 1f48e75c5c1d270610115edfd8742691188d881f Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Tue, 12 Sep 2017 11:24:45 +0200
Subject: [PATCH] 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 <github@gone.nl>
---
 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() {