Example

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

example/go.mod

@@ -0,0 +1,17 @@
+module github.com/crazy-max/yamldocs/example
+
+go 1.16
+
+require (
+	github.com/crazy-max/yamldocs v0.0.0
+	github.com/docker/buildx v0.6.0
+	github.com/docker/cli v20.10.7+incompatible
+	github.com/spf13/cobra v1.2.1
+	github.com/spf13/pflag v1.0.5
+)
+
+replace (
+	github.com/crazy-max/yamldocs => ../
+	github.com/docker/cli => github.com/docker/cli v20.10.3-0.20210702143511-f782d1355eff+incompatible
+	github.com/docker/docker => github.com/docker/docker v20.10.3-0.20210609100121-ef4d47340142+incompatible
+)

example/main.go

@@ -0,0 +1,118 @@
+package main
+
+import (
+	"fmt"
+	"io/ioutil"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/crazy-max/yamldocs"
+	"github.com/docker/buildx/commands"
+	"github.com/docker/cli/cli/command"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+const descriptionSourcePath = "docs/reference/"
+
+func generateCliYaml(opts *options) error {
+	dockerCLI, err := command.NewDockerCli()
+	if err != nil {
+		return err
+	}
+	cmd := &cobra.Command{
+		Use:   "docker [OPTIONS] COMMAND [ARG...]",
+		Short: "The base command for the Docker CLI.",
+	}
+	cmd.AddCommand(commands.NewRootCmd("buildx", true, dockerCLI))
+	disableFlagsInUseLine(cmd)
+	source := filepath.Join(opts.source, descriptionSourcePath)
+	fmt.Println("Markdown source:", source)
+	if err := loadLongDescription(cmd, source); err != nil {
+		return err
+	}
+
+	if err := os.MkdirAll(opts.target, 0755); err != nil {
+		return err
+	}
+
+	cmd.DisableAutoGenTag = true
+	return yamldocs.GenYamlTree(cmd, opts.target)
+}
+
+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
+	})
+}
+
+// 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)
+	}
+	fn(root)
+}
+
+func loadLongDescription(parentCmd *cobra.Command, path string) error {
+	for _, cmd := range parentCmd.Commands() {
+		if cmd.HasSubCommands() {
+			if err := loadLongDescription(cmd, path); err != nil {
+				return err
+			}
+		}
+		name := cmd.CommandPath()
+		log.Println("INFO: Generating docs for", name)
+		if i := strings.Index(name, " "); i >= 0 {
+			// remove root command / binary name
+			name = name[i+1:]
+		}
+		if name == "" {
+			continue
+		}
+		mdFile := strings.ReplaceAll(name, " ", "_") + ".md"
+		fullPath := filepath.Join(path, mdFile)
+		content, err := ioutil.ReadFile(fullPath)
+		if os.IsNotExist(err) {
+			log.Printf("WARN: %s does not exist, skipping\n", mdFile)
+			continue
+		}
+		if err != nil {
+			return err
+		}
+		yamldocs.ApplyDescriptionAndExamples(cmd, string(content))
+	}
+	return nil
+}
+
+type options struct {
+	source string
+	target string
+}
+
+func parseArgs() (*options, error) {
+	opts := &options{}
+	cwd, _ := os.Getwd()
+	flags := pflag.NewFlagSet(os.Args[0], pflag.ContinueOnError)
+	flags.StringVar(&opts.source, "root", cwd, "Path to project root")
+	flags.StringVar(&opts.target, "target", "/tmp", "Target path for generated yaml files")
+	err := flags.Parse(os.Args[1:])
+	return opts, err
+}
+
+func main() {
+	opts, err := parseArgs()
+	if err != nil {
+		log.Println(err)
+	}
+	fmt.Println("Project root:   ", opts.source)
+	fmt.Println("YAML output dir:", opts.target)
+	if err := generateCliYaml(opts); err != nil {
+		log.Println("Failed to generate yaml files:", err)
+	}
+}