Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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>
This commit is contained in:
Sebastiaan van Stijn 2017-09-12 11:24:45 +02:00
parent a8ba6f93d9
commit 1f48e75c5c
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
1 changed files with 16 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/yaml/yaml.go
View File

@ -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() {