From cef61c46a3a246cbcfb5329a3e069f001b73865f Mon Sep 17 00:00:00 2001 From: CrazyMax Date: Tue, 17 Aug 2021 13:14:39 +0200 Subject: [PATCH] Enhance README Signed-off-by: CrazyMax --- README.md | 108 +++++++++++++++++++++++++++++++++++++++++++--- docgen_md.go | 2 +- docgen_yaml.go | 5 +-- example/README.md | 3 +- example/main.go | 2 +- 5 files changed, 109 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index bf413d4..9899791 100644 --- a/README.md +++ b/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 diff --git a/docgen_md.go b/docgen_md.go index b723eba..dd38ff6 100644 --- a/docgen_md.go +++ b/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) diff --git a/docgen_yaml.go b/docgen_yaml.go index d224e0b..608c1f1 100644 --- a/docgen_yaml.go +++ b/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 { diff --git a/example/README.md b/example/README.md index a4d5e7d..f4d8ad4 100644 --- a/example/README.md +++ b/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 diff --git a/example/main.go b/example/main.go index 4a5acf6..675b90e 100644 --- a/example/main.go +++ b/example/main.go @@ -25,7 +25,7 @@ import ( "github.com/spf13/cobra" ) -const sourcePath = "docs/reference/" +const sourcePath = "docs/" func main() { log.SetFlags(0)