Merge pull request #16 from crazy-max/custom-usage

annotation to specify code delimiter for flag usage

annotation/annotation.go

@@ -0,0 +1,23 @@
+// Copyright 2021 cli-docs-tool authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package annotation
+
+const (
+	// ExternalURL specifies an external link annotation
+	ExternalURL = "docs.external.url"
+	// CodeDelimiter specifies the char that will be converted as code backtick.
+	// Can be used on cmd for inheritance or a specific flag.
+	CodeDelimiter = "docs.code-delimiter"
+)

clidocstool.go

@@ -22,11 +22,6 @@ import (
 	"github.com/spf13/cobra"
 )
 
-const (
-	// AnnotationExternalUrl specifies an external link annotation
-	AnnotationExternalUrl = "docs.external.url"
-)
-
 // Options defines options for cli-docs-tool
 type Options struct {
 	Root      *cobra.Command

clidocstool_md.go

@@ -24,6 +24,7 @@ import (
 	"strings"
 	"text/template"
 
+	"github.com/docker/cli-docs-tool/annotation"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
@@ -51,6 +52,18 @@ func (c *Client) GenMarkdownTree(cmd *cobra.Command) error {
 	sourcePath := filepath.Join(c.source, mdFile)
 	targetPath := filepath.Join(c.target, mdFile)
 
+	// check recursively to handle inherited annotations
+	for curr := cmd; curr != nil; curr = curr.Parent() {
+		if _, ok := cmd.Annotations[annotation.CodeDelimiter]; !ok {
+			if cd, cok := curr.Annotations[annotation.CodeDelimiter]; cok {
+				if cmd.Annotations == nil {
+					cmd.Annotations = map[string]string{}
+				}
+				cmd.Annotations[annotation.CodeDelimiter] = cd
+			}
+		}
+	}
+
 	if !fileExists(sourcePath) {
 		var icBuf bytes.Buffer
 		icTpl, err := template.New("ic").Option("missingkey=error").Parse(`# {{ .Command }}
@@ -120,7 +133,7 @@ func mdFilename(cmd *cobra.Command) string {
 
 func mdMakeLink(txt, link string, f *pflag.Flag, isAnchor bool) string {
 	link = "#" + link
-	annotations, ok := f.Annotations[AnnotationExternalUrl]
+	annotations, ok := f.Annotations[annotation.ExternalURL]
 	if ok && len(annotations) > 0 {
 		link = annotations[0]
 	} else {
@@ -186,7 +199,13 @@ func mdCmdOutput(cmd *cobra.Command, old string) (string, error) {
 			}
 			name += "`"
 			name = mdMakeLink(name, f.Name, f, isLink)
-			fmt.Fprintf(b, "%s | %s |\n", mdEscapePipe(name), mdEscapePipe(f.Usage))
+			usage := f.Usage
+			if cd, ok := f.Annotations[annotation.CodeDelimiter]; ok {
+				usage = strings.ReplaceAll(usage, cd[0], "`")
+			} else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok {
+				usage = strings.ReplaceAll(usage, cd, "`")
+			}
+			fmt.Fprintf(b, "%s | %s |\n", mdEscapePipe(name), mdEscapePipe(usage))
 		})
 		fmt.Fprintln(b, "")
 	}

clidocstool_test.go

@@ -21,6 +21,7 @@ import (
 	"path/filepath"
 	"testing"
 
+	"github.com/docker/cli-docs-tool/annotation"
 	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -47,7 +48,11 @@ func init() {
 	}
 	buildxCmd = &cobra.Command{
 		Use:   "buildx",
-		Short: "Build with BuildKit",
+		Short: "Docker Buildx",
+		Long:  `Extended build capabilities with BuildKit`,
+		Annotations: map[string]string{
+			annotation.CodeDelimiter: `"`,
+		},
 	}
 	buildxBuildCmd = &cobra.Command{
 		Use:     "build [OPTIONS] PATH | URL | -",
@@ -65,39 +70,103 @@ func init() {
 	buildxPFlags.String("builder", os.Getenv("BUILDX_BUILDER"), "Override the configured builder instance")
 
 	buildxBuildFlags := buildxBuildCmd.Flags()
-	buildxBuildFlags.Bool("push", false, "Shorthand for --output=type=registry")
-	buildxBuildFlags.Bool("load", false, "Shorthand for --output=type=docker")
-	buildxBuildFlags.StringArrayP("tag", "t", []string{}, "Name and optionally a tag in the 'name:tag' format")
-	buildxBuildFlags.SetAnnotation("tag", AnnotationExternalUrl, []string{"https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t"})
+
+	var ignore string
+	var ignoreSlice []string
+	var ignoreBool bool
+	var ignoreInt int64
+
+	buildxBuildFlags.StringSlice("add-host", []string{}, `Add a custom host-to-IP mapping (format: 'host:ip')`)
+	buildxBuildFlags.SetAnnotation("add-host", annotation.ExternalURL, []string{"https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host"})
+	buildxBuildFlags.SetAnnotation("add-host", annotation.CodeDelimiter, []string{`'`})
+
+	buildxBuildFlags.StringSlice("allow", []string{}, `Allow extra privileged entitlement (e.g., "network.host", "security.insecure")`)
+
 	buildxBuildFlags.StringArray("build-arg", []string{}, "Set build-time variables")
-	buildxBuildFlags.SetAnnotation("build-arg", AnnotationExternalUrl, []string{"https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg"})
-	buildxBuildFlags.StringP("file", "f", "", "Name of the Dockerfile (Default is 'PATH/Dockerfile')")
-	buildxBuildFlags.SetAnnotation("file", AnnotationExternalUrl, []string{"https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f"})
+	buildxBuildFlags.SetAnnotation("build-arg", annotation.ExternalURL, []string{"https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg"})
+
+	buildxBuildFlags.StringArray("cache-from", []string{}, `External cache sources (e.g., "user/app:cache", "type=local,src=path/to/dir")`)
+
+	buildxBuildFlags.StringArray("cache-to", []string{}, `Cache export destinations (e.g., "user/app:cache", "type=local,dest=path/to/dir")`)
+
+	buildxBuildFlags.String("cgroup-parent", "", "Optional parent cgroup for the container")
+	buildxBuildFlags.SetAnnotation("cgroup-parent", annotation.ExternalURL, []string{"https://docs.docker.com/engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent"})
+
+	buildxBuildFlags.StringP("file", "f", "", `Name of the Dockerfile (default: "PATH/Dockerfile")`)
+	buildxBuildFlags.SetAnnotation("file", annotation.ExternalURL, []string{"https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f"})
+
+	buildxBuildFlags.String("iidfile", "", "Write the image ID to the file")
+
 	buildxBuildFlags.StringArray("label", []string{}, "Set metadata for an image")
-	buildxBuildFlags.StringArray("cache-from", []string{}, "External cache sources (eg. user/app:cache, type=local,src=path/to/dir)")
-	buildxBuildFlags.StringArray("cache-to", []string{}, "Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir)")
-	buildxBuildFlags.String("target", "", "Set the target build stage to build.")
-	buildxBuildFlags.SetAnnotation("target", AnnotationExternalUrl, []string{"https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target"})
-	buildxBuildFlags.StringSlice("allow", []string{}, "Allow extra privileged entitlement, e.g. network.host, security.insecure")
+
+	buildxBuildFlags.Bool("load", false, `Shorthand for "--output=type=docker"`)
+
+	buildxBuildFlags.String("network", "default", `Set the networking mode for the "RUN" instructions during build`)
+
+	buildxBuildFlags.StringArrayP("output", "o", []string{}, `Output destination (format: "type=local,dest=path")`)
+
 	buildxBuildFlags.StringArray("platform", []string{}, "Set target platform for build")
-	buildxBuildFlags.StringArray("secret", []string{}, "Secret file to expose to the build: id=mysecret,src=/local/secret")
-	buildxBuildFlags.StringArray("ssh", []string{}, "SSH agent socket or keys to expose to the build (format: `default|<id>[=<socket>|<key>[,<key>]]`)")
-	buildxBuildFlags.StringArrayP("output", "o", []string{}, "Output destination (format: type=local,dest=path)")
-	// not implemented
-	buildxBuildFlags.String("network", "default", "Set the networking mode for the RUN instructions during build")
-	buildxBuildFlags.StringSlice("add-host", []string{}, "Add a custom host-to-IP mapping (host:ip)")
-	buildxBuildFlags.SetAnnotation("add-host", AnnotationExternalUrl, []string{"https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host"})
-	buildxBuildFlags.String("iidfile", "", "Write the image ID to the file")
-	// hidden flags
+
+	buildxBuildFlags.Bool("push", false, `Shorthand for "--output=type=registry"`)
+
 	buildxBuildFlags.BoolP("quiet", "q", false, "Suppress the build output and print image ID on success")
-	buildxBuildFlags.MarkHidden("quiet")
-	buildxBuildFlags.Bool("squash", false, "Squash newly built layers into a single new layer")
-	buildxBuildFlags.MarkHidden("squash")
-	buildxBuildFlags.String("ulimit", "", "Ulimit options")
-	buildxBuildFlags.MarkHidden("ulimit")
-	buildxBuildFlags.StringSlice("security-opt", []string{}, "Security options")
+
+	buildxBuildFlags.StringArray("secret", []string{}, `Secret file to expose to the build (format: "id=mysecret,src=/local/secret")`)
+
+	buildxBuildFlags.StringVar(&ignore, "shm-size", "", `Size of "/dev/shm"`)
+
+	buildxBuildFlags.StringArray("ssh", []string{}, `SSH agent socket or keys to expose to the build (format: "default|<id>[=<socket>|<key>[,<key>]]")`)
+
+	buildxBuildFlags.StringArrayP("tag", "t", []string{}, `Name and optionally a tag (format: "name:tag")`)
+	buildxBuildFlags.SetAnnotation("tag", annotation.ExternalURL, []string{"https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t"})
+
+	buildxBuildFlags.String("target", "", "Set the target build stage to build.")
+	buildxBuildFlags.SetAnnotation("target", annotation.ExternalURL, []string{"https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target"})
+
+	buildxBuildFlags.StringVar(&ignore, "ulimit", "", "Ulimit options")
+
+	// hidden flags
+	buildxBuildFlags.BoolVar(&ignoreBool, "compress", false, "Compress the build context using gzip")
+	buildxBuildFlags.MarkHidden("compress")
+
+	buildxBuildFlags.StringVar(&ignore, "isolation", "", "Container isolation technology")
+	buildxBuildFlags.MarkHidden("isolation")
+	buildxBuildFlags.SetAnnotation("isolation", "flag-warn", []string{"isolation flag is deprecated with BuildKit."})
+
+	buildxBuildFlags.StringSliceVar(&ignoreSlice, "security-opt", []string{}, "Security options")
 	buildxBuildFlags.MarkHidden("security-opt")
-	buildxBuildFlags.Bool("compress", false, "Compress the build context using gzip")
+	buildxBuildFlags.SetAnnotation("security-opt", "flag-warn", []string{`security-opt flag is deprecated. "RUN --security=insecure" should be used with BuildKit.`})
+
+	buildxBuildFlags.BoolVar(&ignoreBool, "squash", false, "Squash newly built layers into a single new layer")
+	buildxBuildFlags.MarkHidden("squash")
+	buildxBuildFlags.SetAnnotation("squash", "flag-warn", []string{"experimental flag squash is removed with BuildKit. You should squash inside build using a multi-stage Dockerfile for efficiency."})
+
+	buildxBuildFlags.StringVarP(&ignore, "memory", "m", "", "Memory limit")
+	buildxBuildFlags.MarkHidden("memory")
+
+	buildxBuildFlags.StringVar(&ignore, "memory-swap", "", `Swap limit equal to memory plus swap: "-1" to enable unlimited swap`)
+	buildxBuildFlags.MarkHidden("memory-swap")
+
+	buildxBuildFlags.Int64VarP(&ignoreInt, "cpu-shares", "c", 0, "CPU shares (relative weight)")
+	buildxBuildFlags.MarkHidden("cpu-shares")
+
+	buildxBuildFlags.Int64Var(&ignoreInt, "cpu-period", 0, "Limit the CPU CFS (Completely Fair Scheduler) period")
+	buildxBuildFlags.MarkHidden("cpu-period")
+
+	buildxBuildFlags.Int64Var(&ignoreInt, "cpu-quota", 0, "Limit the CPU CFS (Completely Fair Scheduler) quota")
+	buildxBuildFlags.MarkHidden("cpu-quota")
+
+	buildxBuildFlags.StringVar(&ignore, "cpuset-cpus", "", `CPUs in which to allow execution ("0-3", "0,1")`)
+	buildxBuildFlags.MarkHidden("cpuset-cpus")
+
+	buildxBuildFlags.StringVar(&ignore, "cpuset-mems", "", `MEMs in which to allow execution ("0-3", "0,1")`)
+	buildxBuildFlags.MarkHidden("cpuset-mems")
+
+	buildxBuildFlags.BoolVar(&ignoreBool, "rm", true, "Remove intermediate containers after a successful build")
+	buildxBuildFlags.MarkHidden("rm")
+
+	buildxBuildFlags.BoolVar(&ignoreBool, "force-rm", false, "Always remove intermediate containers")
+	buildxBuildFlags.MarkHidden("force-rm")
 
 	buildxCmd.AddCommand(buildxBuildCmd)
 	buildxCmd.AddCommand(buildxStopCmd)

clidocstool_yaml.go

@@ -24,6 +24,7 @@ import (
 	"sort"
 	"strings"
 
+	"github.com/docker/cli-docs-tool/annotation"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 	"gopkg.in/yaml.v2"
@@ -165,7 +166,7 @@ func (c *Client) genYamlCustom(cmd *cobra.Command, w io.Writer) error {
 		cliDoc.Usage = cmd.UseLine()
 	}
 
-	// Check recursively so that, e.g., `docker stack ls` returns the same output as `docker stack`
+	// check recursively to handle inherited annotations
 	for curr := cmd; curr != nil; curr = curr.Parent() {
 		if v, ok := curr.Annotations["version"]; ok && cliDoc.MinAPIVersion == "" {
 			cliDoc.MinAPIVersion = v
@@ -185,6 +186,14 @@ func (c *Client) genYamlCustom(cmd *cobra.Command, w io.Writer) error {
 		if o, ok := curr.Annotations["ostype"]; ok && cliDoc.OSType == "" {
 			cliDoc.OSType = o
 		}
+		if _, ok := cmd.Annotations[annotation.CodeDelimiter]; !ok {
+			if cd, cok := curr.Annotations[annotation.CodeDelimiter]; cok {
+				if cmd.Annotations == nil {
+					cmd.Annotations = map[string]string{}
+				}
+				cmd.Annotations[annotation.CodeDelimiter] = cd
+			}
+		}
 	}
 
 	anchors := make(map[string]struct{})
@@ -196,11 +205,11 @@ func (c *Client) genYamlCustom(cmd *cobra.Command, w io.Writer) error {
 
 	flags := cmd.NonInheritedFlags()
 	if flags.HasFlags() {
-		cliDoc.Options = genFlagResult(flags, anchors)
+		cliDoc.Options = genFlagResult(cmd, flags, anchors)
 	}
 	flags = cmd.InheritedFlags()
 	if flags.HasFlags() {
-		cliDoc.InheritedOptions = genFlagResult(flags, anchors)
+		cliDoc.InheritedOptions = genFlagResult(cmd, flags, anchors)
 	}
 
 	if hasSeeAlso(cmd) {
@@ -238,7 +247,7 @@ func (c *Client) genYamlCustom(cmd *cobra.Command, w io.Writer) error {
 	return nil
 }
 
-func genFlagResult(flags *pflag.FlagSet, anchors map[string]struct{}) []cmdOption {
+func genFlagResult(cmd *cobra.Command, flags *pflag.FlagSet, anchors map[string]struct{}) []cmdOption {
 	var (
 		result []cmdOption
 		opt    cmdOption
@@ -263,12 +272,19 @@ func genFlagResult(flags *pflag.FlagSet, anchors map[string]struct{}) []cmdOptio
 			Option:       flag.Name,
 			ValueType:    flag.Value.Type(),
 			DefaultValue: forceMultiLine(flag.DefValue, defaultValueMaxWidth),
-			Description:  forceMultiLine(flag.Usage, descriptionMaxWidth),
 			Deprecated:   len(flag.Deprecated) > 0,
 			Hidden:       flag.Hidden,
 		}
 
-		if v, ok := flag.Annotations[AnnotationExternalUrl]; ok && len(v) > 0 {
+		usage := flag.Usage
+		if cd, ok := flag.Annotations[annotation.CodeDelimiter]; ok {
+			usage = strings.ReplaceAll(usage, cd[0], "`")
+		} else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok {
+			usage = strings.ReplaceAll(usage, cd, "`")
+		}
+		opt.Description = forceMultiLine(usage, descriptionMaxWidth)
+
+		if v, ok := flag.Annotations[annotation.ExternalURL]; ok && len(v) > 0 {
 			opt.DetailsURL = strings.TrimPrefix(v[0], "https://docs.docker.com")
 		} else if _, ok = anchors[flag.Name]; ok {
 			opt.DetailsURL = "#" + flag.Name

example/main.go

@@ -46,8 +46,8 @@ func gen(opts *options) error {
 
 	// root command
 	cmd := &cobra.Command{
-		Use:   "buildx",
-		Short: "Build with BuildKit",
+		Use:   "docker [OPTIONS] COMMAND [ARG...]",
+		Short: "The base command for the Docker CLI.",
 	}
 
 	// subcommand for the plugin

fixtures/buildx.md

@@ -1,7 +1,7 @@
 # docker buildx
 
 <!---MARKER_GEN_START-->
-Build with BuildKit
+Extended build capabilities with BuildKit
 
 ### Subcommands
 

fixtures/buildx_build.md

@@ -11,25 +11,28 @@ Start a build
 
 | Name | Description |
 | --- | --- |
-| [`--add-host stringSlice`](https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host) | Add a custom host-to-IP mapping (host:ip) |
-| `--allow stringSlice` | Allow extra privileged entitlement, e.g. network.host, security.insecure |
+| [`--add-host stringSlice`](https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host) | Add a custom host-to-IP mapping (format: `host:ip`) |
+| `--allow stringSlice` | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) |
 | [`--build-arg stringArray`](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg) | Set build-time variables |
 | `--builder string` | Override the configured builder instance |
-| `--cache-from stringArray` | External cache sources (eg. user/app:cache, type=local,src=path/to/dir) |
-| `--cache-to stringArray` | Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir) |
-| `--compress` | Compress the build context using gzip |
-| [`-f`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f), [`--file string`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f) | Name of the Dockerfile (Default is 'PATH/Dockerfile') |
+| `--cache-from stringArray` | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) |
+| `--cache-to stringArray` | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`) |
+| [`--cgroup-parent string`](https://docs.docker.com/engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent) | Optional parent cgroup for the container |
+| [`-f`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f), [`--file string`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f) | Name of the Dockerfile (default: `PATH/Dockerfile`) |
 | `--iidfile string` | Write the image ID to the file |
 | `--label stringArray` | Set metadata for an image |
-| `--load` | Shorthand for --output=type=docker |
-| `--network string` | Set the networking mode for the RUN instructions during build |
-| `-o`, `--output stringArray` | Output destination (format: type=local,dest=path) |
+| `--load` | Shorthand for `--output=type=docker` |
+| `--network string` | Set the networking mode for the `RUN` instructions during build |
+| `-o`, `--output stringArray` | Output destination (format: `type=local,dest=path`) |
 | `--platform stringArray` | Set target platform for build |
-| `--push` | Shorthand for --output=type=registry |
-| `--secret stringArray` | Secret file to expose to the build: id=mysecret,src=/local/secret |
+| `--push` | Shorthand for `--output=type=registry` |
+| `-q`, `--quiet` | Suppress the build output and print image ID on success |
+| `--secret stringArray` | Secret file to expose to the build (format: `id=mysecret,src=/local/secret`) |
+| `--shm-size string` | Size of `/dev/shm` |
 | `--ssh stringArray` | SSH agent socket or keys to expose to the build (format: `default\|<id>[=<socket>\|<key>[,<key>]]`) |
-| [`-t`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t), [`--tag stringArray`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t) | Name and optionally a tag in the 'name:tag' format |
+| [`-t`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t), [`--tag stringArray`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t) | Name and optionally a tag (format: `name:tag`) |
 | [`--target string`](https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target) | Set the target build stage to build. |
+| `--ulimit string` | Ulimit options |
 
 
 <!---MARKER_GEN_END-->

fixtures/docker_buildx.yaml

@@ -1,6 +1,6 @@
 command: docker buildx
-short: Build with BuildKit
-long: Build with BuildKit
+short: Docker Buildx
+long: Extended build capabilities with BuildKit
 pname: docker
 plink: docker.yaml
 cname: