New opts for setting target and plugin capabilities

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

Author: crazy-max

.github/workflows/godev.yml

@@ -9,6 +9,7 @@ on:
 
 jobs:
   update:
+    if: startsWith(github.ref, 'refs/tags/')
     runs-on: ubuntu-latest
     steps:
       -

.github/workflows/test.yml

@@ -41,3 +41,20 @@ jobs:
         uses: codecov/codecov-action@v2
         with:
           file: ./coverage.txt
+
+  example:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+      -
+        name: Set up Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: 1.16
+      -
+        name: Run
+        run: |
+          go run main.go
+        working-directory: ./example

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

clidocstool.go

@@ -15,38 +15,108 @@
 package clidocstool
 
 import (
+	"io"
+	"os"
+
+	"github.com/pkg/errors"
 	"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 {
+// 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.
+// DisableFlagsInUseLine sets the DisableFlagsInUseLine flag on all
+// commands within the tree rooted at cmd.
+func (c *Client) DisableFlagsInUseLine() {
+	visitAll(c.root, func(ccmd *cobra.Command) {
+		// do not add a `[flags]` to the end of the usage line.
+		ccmd.DisableFlagsInUseLine = true
+	})
+}
+
+// visitAll traverses 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)) {
+func visitAll(root *cobra.Command, fn func(*cobra.Command)) {
 	for _, cmd := range root.Commands() {
-		VisitAll(cmd, fn)
+		visitAll(cmd, fn)
 	}
 	fn(root)
 }
 
-// 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 fileExists(f string) bool {
+	info, err := os.Stat(f)
+	if os.IsNotExist(err) {
+		return false
+	}
+	return !info.IsDir()
+}
+
+func copyFile(src string, dest string) error {
+	srcFile, err := os.Open(src)
+	if err != nil {
+		return err
+	}
+	defer srcFile.Close()
+
+	destFile, err := os.Create(dest)
+	if err != nil {
+		return err
+	}
+	defer destFile.Close()
+
+	if _, err = io.Copy(destFile, srcFile); err != nil {
+		return err
+	}
+	return destFile.Sync()
 }

clidocstool_md.go

@@ -31,21 +31,25 @@ import (
 
 // 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() {
+
+	// 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 +67,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
 	}
@@ -91,12 +97,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 errors.Wrapf(err, "failed to write %s", targetPath)
 	}
 
 	return nil

clidocstool_md_test.go

@@ -17,67 +17,39 @@ package clidocstool
 import (
 	"io/ioutil"
 	"os"
+	"path"
 	"path/filepath"
 	"testing"
 
-	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
 //nolint:errcheck
 func TestGenMarkdownTree(t *testing.T) {
-	c := &cobra.Command{Use: "do [OPTIONS] arg1 arg2"}
-	s := &cobra.Command{Use: "sub [OPTIONS] arg1 arg2"}
-
-	flags := s.Flags()
-	_ = flags.Bool("push", false, "Shorthand for --output=type=registry")
-	_ = flags.Bool("load", false, "Shorthand for --output=type=docker")
-	_ = flags.StringArrayP("tag", "t", []string{}, "Name and optionally a tag in the 'name:tag' format")
-	flags.SetAnnotation("tag", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t"})
-	_ = flags.StringArray("build-arg", []string{}, "Set build-time variables")
-	flags.SetAnnotation("build-arg", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg"})
-	_ = flags.StringP("file", "f", "", "Name of the Dockerfile (Default is 'PATH/Dockerfile')")
-	flags.SetAnnotation("file", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f"})
-	_ = flags.StringArray("label", []string{}, "Set metadata for an image")
-	_ = flags.StringArray("cache-from", []string{}, "External cache sources (eg. user/app:cache, type=local,src=path/to/dir)")
-	_ = flags.StringArray("cache-to", []string{}, "Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir)")
-	_ = flags.String("target", "", "Set the target build stage to build.")
-	flags.SetAnnotation("target", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target"})
-	_ = flags.StringSlice("allow", []string{}, "Allow extra privileged entitlement, e.g. network.host, security.insecure")
-	_ = flags.StringArray("platform", []string{}, "Set target platform for build")
-	_ = flags.StringArray("secret", []string{}, "Secret file to expose to the build: id=mysecret,src=/local/secret")
-	_ = flags.StringArray("ssh", []string{}, "SSH agent socket or keys to expose to the build (format: `default|<id>[=<socket>|<key>[,<key>]]`)")
-	_ = flags.StringArrayP("output", "o", []string{}, "Output destination (format: type=local,dest=path)")
-	// not implemented
-	_ = flags.String("network", "default", "Set the networking mode for the RUN instructions during build")
-	_ = flags.StringSlice("add-host", []string{}, "Add a custom host-to-IP mapping (host:ip)")
-	_ = flags.SetAnnotation("add-host", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host"})
-	_ = flags.String("iidfile", "", "Write the image ID to the file")
-	// hidden flags
-	_ = flags.BoolP("quiet", "q", false, "Suppress the build output and print image ID on success")
-	flags.MarkHidden("quiet")
-	_ = flags.Bool("squash", false, "Squash newly built layers into a single new layer")
-	flags.MarkHidden("squash")
-	_ = flags.String("ulimit", "", "Ulimit options")
-	flags.MarkHidden("ulimit")
-	_ = flags.StringSlice("security-opt", []string{}, "Security options")
-	flags.MarkHidden("security-opt")
-	_ = flags.Bool("compress", false, "Compress the build context using gzip")
-
-	c.AddCommand(s)
-
 	tmpdir, err := ioutil.TempDir("", "test-gen-markdown-tree")
 	require.NoError(t, err)
-
 	defer os.RemoveAll(tmpdir)
-	require.NoError(t, GenMarkdownTree(c, tmpdir))
 
-	fres := filepath.Join(tmpdir, "sub.md")
-	require.FileExists(t, fres)
-	bres, err := ioutil.ReadFile(fres)
-	require.NoError(t, err)
-	bexc, err := ioutil.ReadFile("fixtures/sub.md")
+	c, err := New(Options{
+		Root:      buildxCmd,
+		SourceDir: tmpdir,
+		Plugin:    true,
+	})
 	require.NoError(t, err)
-	assert.Equal(t, string(bres), string(bexc))
+	require.NoError(t, c.GenMarkdownTree(buildxCmd))
+
+	for _, tt := range []string{"buildx.md", "buildx_build.md"} {
+		tt := tt
+		t.Run(tt, func(t *testing.T) {
+			fres := filepath.Join(tmpdir, tt)
+			require.FileExists(t, fres)
+			bres, err := ioutil.ReadFile(fres)
+			require.NoError(t, err)
+
+			bexc, err := ioutil.ReadFile(path.Join("fixtures", tt))
+			require.NoError(t, err)
+			assert.Equal(t, string(bexc), string(bres))
+		})
+	}
 }