Rename package and move `LoadLongDescription` func

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

.dockerignore

@@ -1 +1,2 @@
 /coverage.txt
+/example/docs

.gitignore

@@ -1 +1,2 @@
 /coverage.txt
+/example/docs

README.md

@@ -1,22 +1,16 @@
-[![PkgGoDev](https://img.shields.io/badge/go.dev-docs-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/docker/yamldocs)
-[![Test Status](https://img.shields.io/github/workflow/status/crazy-max/yamldocs/build?label=build&logo=github&style=flat-square)](https://github.com/docker/yamldocs/actions?query=workflow%3Atest)
-[![Go Report Card](https://goreportcard.com/badge/github.com/docker/yamldocs)](https://goreportcard.com/report/github.com/docker/yamldocs)
-[![Codecovs](https://img.shields.io/codecov/c/github/crazy-max/yamldocs?logo=codecov&style=flat-square)](https://codecov.io/gh/crazy-max/yamldocs)
+[![PkgGoDev](https://img.shields.io/badge/go.dev-docs-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/docker/docgen)
+[![Test Status](https://img.shields.io/github/workflow/status/crazy-max/docgen/build?label=build&logo=github&style=flat-square)](https://github.com/docker/docgen/actions?query=workflow%3Atest)
+[![Go Report Card](https://goreportcard.com/badge/github.com/docker/docgen)](https://goreportcard.com/report/github.com/docker/docgen)
+[![Codecovs](https://img.shields.io/codecov/c/github/crazy-max/docgen?logo=codecov&style=flat-square)](https://codecov.io/gh/crazy-max/docgen)
 
 ## About
 
-YAML Docs generator specially crafted for [Docker CLI](https://github.com/docker/cli) plugins.
+Doc generator specially crafted for [Docker CLI](https://github.com/docker/cli) plugins.
 
 ## Installation
 
 ```
-go get github.com/docker/yamldocs
+go get github.com/docker/docgen
 ```
 
-## Usage
-
-```go
-package main
-
-...
-```
+Basic usage available in [example](example) folder.

cobra.go

@@ -0,0 +1,22 @@
+package docgen
+
+import "github.com/spf13/cobra"
+
+// 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)
+}
+
+// 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
+	})
+}

docgen.go

@@ -0,0 +1 @@
+package docgen

docgen_yaml.go

@@ -1,8 +1,10 @@
-package yamldocs
+package docgen
 
 import (
 	"fmt"
 	"io"
+	"io/ioutil"
+	"log"
 	"os"
 	"path/filepath"
 	"sort"
@@ -318,9 +320,41 @@ func hasSeeAlso(cmd *cobra.Command) bool {
 	return false
 }
 
-// ApplyDescriptionAndExamples fills in cmd.Long and cmd.Example with the
+// LoadLongDescription gets long descriptions and examples from markdown.
+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
+		}
+		applyDescriptionAndExamples(cmd, string(content))
+	}
+	return nil
+}
+
+// applyDescriptionAndExamples fills in cmd.Long and cmd.Example with the
 // "Description" and "Examples" H2 sections in  mdString (if present).
-func ApplyDescriptionAndExamples(cmd *cobra.Command, mdString string) {
+func applyDescriptionAndExamples(cmd *cobra.Command, mdString string) {
 	sections := getSections(mdString)
 	var (
 		anchors []string

docgen_yaml_test.go

@@ -1,4 +1,4 @@
-package yamldocs
+package docgen
 
 import (
 	"io/ioutil"

example/go.mod

@@ -1,17 +1,16 @@
-module github.com/docker/yamldocs/example
+module github.com/docker/docgen/example
 
 go 1.16
 
 require (
 	github.com/docker/buildx v0.6.0
 	github.com/docker/cli v20.10.7+incompatible
-	github.com/docker/yamldocs v0.0.0
+	github.com/docker/docgen v0.0.0
 	github.com/spf13/cobra v1.2.1
-	github.com/spf13/pflag v1.0.5
 )
 
 replace (
 	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
-	github.com/docker/yamldocs => ../
+	github.com/docker/docgen => ../
 )

example/main.go

@@ -1,118 +1,46 @@
 package main
 
 import (
-	"fmt"
-	"io/ioutil"
 	"log"
 	"os"
 	"path/filepath"
-	"strings"
 
 	"github.com/docker/buildx/commands"
 	"github.com/docker/cli/cli/command"
-	"github.com/docker/yamldocs"
+	"github.com/docker/docgen"
 	"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
-}
+const sourcePath = "docs/reference/"
 
 func main() {
-	opts, err := parseArgs()
+	log.SetFlags(0)
+
+	dockerCLI, err := command.NewDockerCli()
 	if err != nil {
-		log.Println(err)
+		log.Printf("error: %+v", 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)
+
+	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))
+	docgen.DisableFlagsInUseLine(cmd)
+
+	cwd, _ := os.Getwd()
+	source := filepath.Join(cwd, sourcePath)
+	if err := docgen.LoadLongDescription(cmd, source); err != nil {
+		log.Printf("error: %+v", err)
+	}
+
+	if err = os.MkdirAll(sourcePath, 0755); err != nil {
+		log.Printf("error: %+v", err)
+	}
+
+	if err = docgen.GenYamlTree(cmd, sourcePath); err != nil {
+		log.Printf("error: %+v", err)
 	}
 }

go.mod

@@ -1,4 +1,4 @@
-module github.com/docker/yamldocs
+module github.com/docker/docgen
 
 go 1.16
 

markdown.go

@@ -1,4 +1,4 @@
-package yamldocs
+package docgen
 
 import (
 	"regexp"

markdown_test.go

@@ -1,4 +1,4 @@
-package yamldocs
+package docgen
 
 import "testing"