switch to cli-docs-tool for yaml docs generation

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>
switch to cli-docs-tool and validate yamldocs

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

.dockerignore

@@ -2,8 +2,11 @@
 /cli/winresources/versioninfo.json
 /cli/winresources/*.syso
 /man/man*/
-/docs/yaml/gen/
+/docs/yaml/
+/docs/vendor/
+/docs/go.sum
 profile.out
 
 # top-level go.mod is not meant to be checked in
 /go.mod
+/go.sum

.github/workflows/validate.yml

@@ -32,3 +32,21 @@ jobs:
         uses: docker/bake-action@v1
         with:
           targets: ${{ matrix.target }}
+
+  validate-make:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - yamldocs # ensure yamldocs target runs fine
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      -
+        name: Run
+        run: |
+          make -f docker.Makefile ${{ matrix.target }}

.gitignore

@@ -13,8 +13,8 @@ Thumbs.db
 /man/man1/
 /man/man5/
 /man/man8/
-/docs/yaml/gen/
 profile.out
 
 # top-level go.mod is not meant to be checked in
 /go.mod
+/go.sum

Makefile

@@ -11,7 +11,7 @@ _:=$(shell ./scripts/warn-outside-container $(MAKECMDGOALS))
 
 .PHONY: clean
 clean: ## remove build artifacts
-	rm -rf ./build/* cli/winresources/rsrc_* ./man/man[1-9] docs/yaml/gen
+	rm -rf ./build/* cli/winresources/rsrc_* ./man/man[1-9] docs/yaml
 
 .PHONY: test
 test: test-unit ## run tests

docs/.gitignore

@@ -0,0 +1,3 @@
+/vendor
+/yaml
+/go.sum

docs/README.md

@@ -28,3 +28,9 @@ the place to edit them.
 
 The docs in the general repo are open-source and we appreciate
 your feedback and pull requests!
+
+# Generate docs
+
+```shell
+$ make -f docker.Makefile yamldocs
+```

docs/generate.go

@@ -0,0 +1,67 @@
+// This file is intended for use with "go run"; it isn't really part of the package.
+
+// +build docsgen
+
+package main
+
+import (
+	"log"
+	"os"
+
+	clidocstool "github.com/docker/cli-docs-tool"
+	"github.com/docker/cli/cli/command"
+	"github.com/docker/cli/cli/command/commands"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+const defaultSourcePath = "docs/reference/commandline/"
+
+type options struct {
+	source string
+	target string
+}
+
+func gen(opts *options) error {
+	log.SetFlags(0)
+
+	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.",
+	}
+	commands.AddCommands(cmd, dockerCLI)
+
+	c, err := clidocstool.New(clidocstool.Options{
+		Root:      cmd,
+		SourceDir: opts.source,
+		TargetDir: opts.target,
+		Plugin:    false,
+	})
+	if err != nil {
+		return err
+	}
+
+	return c.GenYamlTree(cmd)
+}
+
+func run() error {
+	opts := &options{}
+	flags := pflag.NewFlagSet(os.Args[0], pflag.ContinueOnError)
+	flags.StringVar(&opts.source, "source", defaultSourcePath, "Docs source folder")
+	flags.StringVar(&opts.target, "target", defaultSourcePath, "Docs target folder")
+	if err := flags.Parse(os.Args[1:]); err != nil {
+		return err
+	}
+	return gen(opts)
+}
+
+func main() {
+	if err := run(); err != nil {
+		log.Printf("ERROR: %+v", err)
+		os.Exit(1)
+	}
+}

docs/go.mod

@@ -0,0 +1,13 @@
+module github.com/docker/cli/docs
+
+// dummy go.mod to avoid dealing with dependencies specific
+// to docs generation and not really part of the project.
+
+go 1.16
+
+//require (
+//	github.com/docker/cli v0.0.0+incompatible
+//	github.com/docker/cli-docs-tool v0.3.0
+//)
+//
+//replace github.com/docker/cli v0.0.0+incompatible => ../

docs/tools.go

@@ -0,0 +1,7 @@
+// +build tools
+
+package main
+
+import (
+	_ "github.com/docker/cli-docs-tool"
+)