Enhance README

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

README.md

@@ -1,18 +1,116 @@
 [![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)
+[![Test Status](https://img.shields.io/github/workflow/status/crazy-max/docgen/build?label=test&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)
 
 ## About
 
-Doc generator specially crafted for [Docker CLI](https://github.com/docker/cli) plugins.
+This is a library containing utilities to generate (reference) documentation
+for the [`docker` CLI](https://github.com/docker/cli) on [docs.docker.com](https://docs.docker.com/reference/).
+
+## Disclaimer
+
+This library is intended for use by Docker's CLIs, and is not intended to be a
+general-purpose utility. Various bits are hard-coded or make assumptions that
+are very specific to our use-case. Contributions are welcome, but we will not
+accept contributions to make this a general-purpose module.
 
 ## Usage
 
-```
-go get github.com/docker/docgen
+To generate the documentation it's recommended to do so using a Go submodule
+in your repository.
+
+We will use the example of `docker/buildx` and create a Go submodule in a
+`docs` folder (recommended):
+
+```console
+$ mkdir docs
+$ cd ./docs
+$ go mod init github.com/docker/buildx/docs
+$ go get github.com/docker/docgen
 ```
 
-Basic usage available in [example](example) folder.
+Your `go.mod` should look like this:
+
+```text
+module github.com/docker/buildx/docs
+
+go 1.16
+
+require (
+	github.com/docker/docgen v0.0.0
+)
+```
+
+Next, create a file named `docgen.go` inside that directory containing the
+following Go code:
+
+```go
+package main
+
+import (
+  "log"
+  "os"
+  "path/filepath"
+
+  "github.com/docker/buildx/commands"
+  "github.com/docker/cli/cli/command"
+  "github.com/docker/docgen"
+  "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))
+  docgen.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 = docgen.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 `docgen.GenTree`.
+
+```console
+$ go run main.go
+INFO: Generating Markdown for "docker buildx bake"
+INFO: Generating Markdown for "docker buildx build"
+INFO: Generating Markdown for "docker buildx create"
+INFO: Generating Markdown for "docker buildx du"
+...
+INFO: Generating YAML for "docker buildx uninstall"
+INFO: Generating YAML for "docker buildx use"
+INFO: Generating YAML for "docker buildx version"
+INFO: Generating YAML for "docker buildx"
+```
+
+Generated docs will be available in the `./docs` folder of the project.
 
 ## Contributing
 

docgen_md.go

@@ -41,7 +41,7 @@ func GenMarkdownTree(cmd *cobra.Command, dir string) error {
 		return nil
 	}
 
-	log.Printf("INFO: Generating Markdown docs for %s", cmd.CommandPath())
+	log.Printf("INFO: Generating Markdown for %q", cmd.CommandPath())
 	mdFile := mdFilename(cmd)
 	fullPath := filepath.Join(dir, mdFile)
 

docgen_yaml.go

@@ -112,7 +112,7 @@ func GenYamlTreeCustom(cmd *cobra.Command, dir string, filePrepender func(string
 	if !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)
@@ -346,7 +346,6 @@ func loadLongDescription(parentCmd *cobra.Command, path string) error {
 			}
 		}
 		name := cmd.CommandPath()
-		log.Println("INFO: Generating YAML docs for", name)
 		if i := strings.Index(name, " "); i >= 0 {
 			// remove root command / binary name
 			name = name[i+1:]
@@ -358,7 +357,7 @@ func loadLongDescription(parentCmd *cobra.Command, path string) error {
 		fullPath := filepath.Join(path, mdFile)
 		content, err := ioutil.ReadFile(fullPath)
 		if os.IsNotExist(err) {
-			log.Printf("WARN: %s does not exist, skipping\n", mdFile)
+			log.Printf("WARN: %s does not exist, skipping Markdown examples for YAML doc\n", mdFile)
 			continue
 		}
 		if err != nil {

example/README.md

@@ -1,6 +1,7 @@
 # Example
 
-The following example will generate YAML and Markdown for [Docker buildx](https://github.com/docker/buildx) CLI plugin.
+The following example will generate YAML and Markdown docs for
+[Docker buildx](https://github.com/docker/buildx) CLI.
 
 ```console
 git clone https://github.com/docker/docgen

example/main.go

@@ -25,7 +25,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-const sourcePath = "docs/reference/"
+const sourcePath = "docs/"
 
 func main() {
 	log.SetFlags(0)