cli: fix builder persistent flag

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

vendor/github.com/docker/cli-docs-tool/README.md

@@ -41,61 +41,10 @@ require (
 )
 ```
 
-Next, create a file named `docgen.go` inside that directory containing the
-following Go code:
+Next, create a file named `main.go` inside that directory containing the
+following Go code from [`example/main.go`](example/main.go).
 
-```go
-package main
-
-import (
-  "log"
-  "os"
-  "path/filepath"
-
-  "github.com/docker/buildx/commands"
-  "github.com/docker/cli/cli/command"
-  clidocstool "github.com/docker/cli-docs-tool"
-  "github.com/spf13/cobra"
-)
-
-const sourcePath = "docs/"
-
-func main() {
-  log.SetFlags(0)
-
-  dockerCLI, err := command.NewDockerCli()
-  if err != nil {
-    log.Printf("ERROR: %+v", err)
-  }
-
-  cmd := &cobra.Command{
-    Use:               "docker [OPTIONS] COMMAND [ARG...]",
-    Short:             "The base command for the Docker CLI.",
-    DisableAutoGenTag: true,
-  }
-
-  cmd.AddCommand(commands.NewRootCmd("buildx", true, dockerCLI))
-  clidocstool.DisableFlagsInUseLine(cmd)
-
-  cwd, _ := os.Getwd()
-  source := filepath.Join(cwd, sourcePath)
-
-  // Make sure "source" folder is created first
-  if err = os.MkdirAll(source, 0755); err != nil {
-    log.Printf("ERROR: %+v", err)
-  }
-  
-  // Generate Markdown and YAML documentation to "source" folder
-  if err = clidocstool.GenTree(cmd, source); err != nil {
-    log.Printf("ERROR: %+v", err)
-  }
-}
-```
-
-Here we create a new instance of Docker CLI with `command.NewDockerCli` and a
-subcommand `commands.NewRootCmd` for `buildx`.
-
-Finally, we generate Markdown and YAML documentation with `clidocstool.GenTree`.
+Running this example should produce the following output:
 
 ```console
 $ go run main.go

vendor/github.com/docker/cli-docs-tool/clidocstool.go

@@ -15,38 +15,90 @@
 package clidocstool
 
 import (
+	"errors"
+	"io"
+	"os"
+
 	"github.com/spf13/cobra"
 )
 
-// GenTree creates yaml and markdown structured ref files for this command
-// and all descendants in the directory given. This function will just
-// call GenMarkdownTree and GenYamlTree functions successively.
-func GenTree(cmd *cobra.Command, dir string) error {
+const (
+	// AnnotationExternalUrl specifies an external link annotation
+	AnnotationExternalUrl = "docs.external.url"
+)
+
+// Options defines options for cli-docs-tool
+type Options struct {
+	Root      *cobra.Command
+	SourceDir string
+	TargetDir string
+	Plugin    bool
+}
+
+// Client represents an active cli-docs-tool object
+type Client struct {
+	root   *cobra.Command
+	source string
+	target string
+	plugin bool
+}
+
+// New initializes a new cli-docs-tool client
+func New(opts Options) (*Client, error) {
+	if opts.Root == nil {
+		return nil, errors.New("root cmd required")
+	}
+	if len(opts.SourceDir) == 0 {
+		return nil, errors.New("source dir required")
+	}
+	c := &Client{
+		root:   opts.Root,
+		source: opts.SourceDir,
+		plugin: opts.Plugin,
+	}
+	if len(opts.TargetDir) == 0 {
+		c.target = c.source
+	} else {
+		c.target = opts.TargetDir
+	}
+	if err := os.MkdirAll(c.target, 0755); err != nil {
+		return nil, err
+	}
+	return c, nil
+}
+
+// GenAllTree creates all structured ref files for this command and
+// all descendants in the directory given.
+func (c *Client) GenAllTree() error {
 	var err error
-	if err = GenMarkdownTree(cmd, dir); err != nil {
+	if err = c.GenMarkdownTree(c.root); err != nil {
 		return err
 	}
-	if err = GenYamlTree(cmd, dir); err != nil {
+	if err = c.GenYamlTree(c.root); err != nil {
 		return err
 	}
 	return nil
 }
 
-// VisitAll will traverse all commands from the root.
-// This is different from the VisitAll of cobra.Command where only parents
-// are checked.
-func VisitAll(root *cobra.Command, fn func(*cobra.Command)) {
-	for _, cmd := range root.Commands() {
-		VisitAll(cmd, fn)
+func fileExists(f string) bool {
+	info, err := os.Stat(f)
+	if os.IsNotExist(err) {
+		return false
 	}
-	fn(root)
+	return !info.IsDir()
 }
 
-// DisableFlagsInUseLine sets the DisableFlagsInUseLine flag on all
-// commands within the tree rooted at cmd.
-func DisableFlagsInUseLine(cmd *cobra.Command) {
-	VisitAll(cmd, func(ccmd *cobra.Command) {
-		// do not add a `[flags]` to the end of the usage line.
-		ccmd.DisableFlagsInUseLine = true
-	})
+func copyFile(src string, dst string) error {
+	sf, err := os.Open(src)
+	if err != nil {
+		return err
+	}
+	defer sf.Close()
+	df, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY, 0o600)
+	if err != nil {
+		return err
+	}
+	defer df.Close()
+	_, err = io.Copy(df, sf)
+	return err
 }

vendor/github.com/docker/cli-docs-tool/clidocstool_md.go

@@ -24,28 +24,34 @@ import (
 	"strings"
 	"text/template"
 
-	"github.com/pkg/errors"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
 // GenMarkdownTree will generate a markdown page for this command and all
 // descendants in the directory given.
-func GenMarkdownTree(cmd *cobra.Command, dir string) error {
-	for _, c := range cmd.Commands() {
-		if err := GenMarkdownTree(c, dir); err != nil {
+func (c *Client) GenMarkdownTree(cmd *cobra.Command) error {
+	for _, sc := range cmd.Commands() {
+		if err := c.GenMarkdownTree(sc); err != nil {
 			return err
 		}
 	}
-	if !cmd.HasParent() {
+
+	// always disable the addition of [flags] to the usage
+	cmd.DisableFlagsInUseLine = true
+
+	// Skip the root command altogether, to prevent generating a useless
+	// md file for plugins.
+	if c.plugin && !cmd.HasParent() {
 		return nil
 	}
 
 	log.Printf("INFO: Generating Markdown for %q", cmd.CommandPath())
 	mdFile := mdFilename(cmd)
-	fullPath := filepath.Join(dir, mdFile)
+	sourcePath := filepath.Join(c.source, mdFile)
+	targetPath := filepath.Join(c.target, mdFile)
 
-	if _, err := os.Stat(fullPath); os.IsNotExist(err) {
+	if !fileExists(sourcePath) {
 		var icBuf bytes.Buffer
 		icTpl, err := template.New("ic").Option("missingkey=error").Parse(`# {{ .Command }}
 
@@ -63,12 +69,14 @@ func GenMarkdownTree(cmd *cobra.Command, dir string) error {
 		}); err != nil {
 			return err
 		}
-		if err = ioutil.WriteFile(fullPath, icBuf.Bytes(), 0644); err != nil {
+		if err = ioutil.WriteFile(targetPath, icBuf.Bytes(), 0644); err != nil {
 			return err
 		}
+	} else if err := copyFile(sourcePath, targetPath); err != nil {
+		return err
 	}
 
-	content, err := ioutil.ReadFile(fullPath)
+	content, err := ioutil.ReadFile(targetPath)
 	if err != nil {
 		return err
 	}
@@ -79,10 +87,10 @@ func GenMarkdownTree(cmd *cobra.Command, dir string) error {
 	end := strings.Index(cs, "<!---MARKER_GEN_END-->")
 
 	if start == -1 {
-		return errors.Errorf("no start marker in %s", mdFile)
+		return fmt.Errorf("no start marker in %s", mdFile)
 	}
 	if end == -1 {
-		return errors.Errorf("no end marker in %s", mdFile)
+		return fmt.Errorf("no end marker in %s", mdFile)
 	}
 
 	out, err := mdCmdOutput(cmd, cs)
@@ -91,12 +99,12 @@ func GenMarkdownTree(cmd *cobra.Command, dir string) error {
 	}
 	cont := cs[:start] + "<!---MARKER_GEN_START-->" + "\n" + out + "\n" + cs[end:]
 
-	fi, err := os.Stat(fullPath)
+	fi, err := os.Stat(targetPath)
 	if err != nil {
 		return err
 	}
-	if err := ioutil.WriteFile(fullPath, []byte(cont), fi.Mode()); err != nil {
-		return errors.Wrapf(err, "failed to write %s", fullPath)
+	if err = ioutil.WriteFile(targetPath, []byte(cont), fi.Mode()); err != nil {
+		return fmt.Errorf("failed to write %s: %w", targetPath, err)
 	}
 
 	return nil
@@ -112,7 +120,7 @@ func mdFilename(cmd *cobra.Command) string {
 
 func mdMakeLink(txt, link string, f *pflag.Flag, isAnchor bool) string {
 	link = "#" + link
-	annotations, ok := f.Annotations["docs.external.url"]
+	annotations, ok := f.Annotations[AnnotationExternalUrl]
 	if ok && len(annotations) > 0 {
 		link = annotations[0]
 	} else {
@@ -153,11 +161,10 @@ func mdCmdOutput(cmd *cobra.Command, old string) (string, error) {
 		fmt.Fprint(b, "\n\n")
 	}
 
-	hasFlags := cmd.Flags().HasAvailableFlags()
-
+	// add inherited flags before checking for flags availability
 	cmd.Flags().AddFlagSet(cmd.InheritedFlags())
 
-	if hasFlags {
+	if cmd.Flags().HasAvailableFlags() {
 		fmt.Fprint(b, "### Options\n\n")
 		fmt.Fprint(b, "| Name | Description |\n")
 		fmt.Fprint(b, "| --- | --- |\n")

vendor/github.com/docker/cli-docs-tool/clidocstool_yaml.go

@@ -74,62 +74,61 @@ type cmdDoc struct {
 // correctly if your command names have `-` in them. If you have `cmd` with two
 // subcmds, `sub` and `sub-third`, and `sub` has a subcommand called `third`
 // it is undefined which help output will be in the file `cmd-sub-third.1`.
-func GenYamlTree(cmd *cobra.Command, dir string) error {
+func (c *Client) GenYamlTree(cmd *cobra.Command) error {
 	emptyStr := func(s string) string { return "" }
-	if err := loadLongDescription(cmd, dir); err != nil {
+	if err := c.loadLongDescription(cmd); err != nil {
 		return err
 	}
-	return GenYamlTreeCustom(cmd, dir, emptyStr)
+	return c.genYamlTreeCustom(cmd, emptyStr)
 }
 
-// GenYamlTreeCustom creates yaml structured ref files.
-func GenYamlTreeCustom(cmd *cobra.Command, dir string, filePrepender func(string) string) error {
-	for _, c := range cmd.Commands() {
-		if !c.Runnable() && !c.HasAvailableSubCommands() {
+// genYamlTreeCustom creates yaml structured ref files.
+func (c *Client) genYamlTreeCustom(cmd *cobra.Command, filePrepender func(string) string) error {
+	for _, sc := range cmd.Commands() {
+		if !sc.Runnable() && !sc.HasAvailableSubCommands() {
 			// skip non-runnable commands without subcommands
 			// but *do* generate YAML for hidden and deprecated commands
 			// the YAML will have those included as metadata, so that the
 			// documentation repository can decide whether or not to present them
 			continue
 		}
-		if err := GenYamlTreeCustom(c, dir, filePrepender); err != nil {
+		if err := c.genYamlTreeCustom(sc, filePrepender); err != nil {
 			return err
 		}
 	}
 
-	// TODO: conditionally skip the root command (for plugins)
-	//
+	// always disable the addition of [flags] to the usage
+	cmd.DisableFlagsInUseLine = true
+
 	// The "root" command used in the generator is just a "stub", and only has a
 	// list of subcommands, but not (e.g.) global options/flags. We should fix
 	// that, so that the YAML file for the docker "root" command contains the
 	// global flags.
-	//
-	// If we're using this code to generate YAML docs for a plugin, the root-
-	// command is even less useful; in that case, the root command represents
-	// the "docker" command, and is a "dummy" with no flags, and only a single
-	// subcommand (the plugin's top command). For plugins, we should skip the
-	// root command altogether, to prevent generating a useless YAML file.
-	if !cmd.HasParent() {
+
+	// Skip the root command altogether, to prevent generating a useless
+	// YAML file for plugins.
+	if c.plugin && !cmd.HasParent() {
 		return nil
 	}
+
 	log.Printf("INFO: Generating YAML for %q", cmd.CommandPath())
 	basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".yaml"
-	filename := filepath.Join(dir, basename)
-	f, err := os.Create(filename)
+	target := filepath.Join(c.target, basename)
+	f, err := os.Create(target)
 	if err != nil {
 		return err
 	}
 	defer f.Close()
 
-	if _, err := io.WriteString(f, filePrepender(filename)); err != nil {
+	if _, err := io.WriteString(f, filePrepender(target)); err != nil {
 		return err
 	}
-	return GenYamlCustom(cmd, f)
+	return c.genYamlCustom(cmd, f)
 }
 
-// GenYamlCustom creates custom yaml output.
+// genYamlCustom creates custom yaml output.
 // nolint: gocyclo
-func GenYamlCustom(cmd *cobra.Command, w io.Writer) error {
+func (c *Client) genYamlCustom(cmd *cobra.Command, w io.Writer) error {
 	const (
 		// shortMaxWidth is the maximum width for the "Short" description before
 		// we force YAML to use multi-line syntax. The goal is to make the total
@@ -144,6 +143,10 @@ func GenYamlCustom(cmd *cobra.Command, w io.Writer) error {
 		longMaxWidth = 74
 	)
 
+	// necessary to add inherited flags otherwise some
+	// fields are not properly declared like usage
+	cmd.Flags().AddFlagSet(cmd.InheritedFlags())
+
 	cliDoc := cmdDoc{
 		Name:       cmd.CommandPath(),
 		Aliases:    strings.Join(cmd.Aliases, ", "),
@@ -263,7 +266,7 @@ func genFlagResult(flags *pflag.FlagSet, anchors map[string]struct{}) []cmdOptio
 			Deprecated:   len(flag.Deprecated) > 0,
 		}
 
-		if v, ok := flag.Annotations["docs.external.url"]; ok && len(v) > 0 {
+		if v, ok := flag.Annotations[AnnotationExternalUrl]; 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
@@ -338,15 +341,15 @@ func hasSeeAlso(cmd *cobra.Command) bool {
 }
 
 // loadLongDescription gets long descriptions and examples from markdown.
-func loadLongDescription(parentCmd *cobra.Command, path string) error {
+func (c *Client) loadLongDescription(parentCmd *cobra.Command) error {
 	for _, cmd := range parentCmd.Commands() {
 		if cmd.HasSubCommands() {
-			if err := loadLongDescription(cmd, path); err != nil {
+			if err := c.loadLongDescription(cmd); err != nil {
 				return err
 			}
 		}
 		name := cmd.CommandPath()
-		if i := strings.Index(name, " "); i >= 0 {
+		if i := strings.Index(name, " "); c.plugin && i >= 0 {
 			// remove root command / binary name
 			name = name[i+1:]
 		}
@@ -354,8 +357,8 @@ func loadLongDescription(parentCmd *cobra.Command, path string) error {
 			continue
 		}
 		mdFile := strings.ReplaceAll(name, " ", "_") + ".md"
-		fullPath := filepath.Join(path, mdFile)
-		content, err := ioutil.ReadFile(fullPath)
+		sourcePath := filepath.Join(c.source, mdFile)
+		content, err := ioutil.ReadFile(sourcePath)
 		if os.IsNotExist(err) {
 			log.Printf("WARN: %s does not exist, skipping Markdown examples for YAML doc\n", mdFile)
 			continue

vendor/github.com/docker/cli-docs-tool/go.mod

@@ -3,7 +3,6 @@ module github.com/docker/cli-docs-tool
 go 1.16
 
 require (
-	github.com/pkg/errors v0.9.1
 	github.com/spf13/cobra v1.2.1
 	github.com/spf13/pflag v1.0.5
 	github.com/stretchr/testify v1.7.0

vendor/github.com/docker/cli-docs-tool/go.sum

@@ -191,8 +191,6 @@ github.com/modern-go/reflect2 v1.0.1/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3Rllmb
 github.com/pascaldekloe/goe v0.0.0-20180627143212-57f6aae5913c/go.mod h1:lzWF7FIEvWOWxwDKqyGYQf6ZUaNfKdP144TG7ZOy1lc=
 github.com/pelletier/go-toml v1.9.3/go.mod h1:u1nR/EPcESfeI/szUZKdtJ0xRNbUoANCkoOuaOx1Y+c=
 github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
-github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
-github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pkg/sftp v1.10.1/go.mod h1:lYOWFsE0bwd1+KfKJaKeuokY15vzFx25BLbzYYoAxZI=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=