Add YAML-docs generation

This is a very quick 'n dirty implementation of the YAML docs generation;
copied from the docker/cli repository with some minor modifications and a
new Makefile target.

Signed-off-by: Sebastiaan van Stijn <[email protected]>

Author: thaJeztah

Makefile

@@ -133,3 +133,9 @@ help: ## this help
 
 .PHONY: cross e2e-cross test check lint test-unit test-e2e coverage coverage-bin coverage-test-unit coverage-test-e2e clean vendor schemas help
 .DEFAULT: all
+
+
+.PHONY: yamldocs
+yamldocs: ## generate documentation YAML files consumed by docs repo
+	mkdir -p ./_build/docs
+	docker build --output type=local,dest=./_build/ -f docs/yaml/Dockerfile .

docs/reference/.keep

@@ -0,0 +1,25 @@
+FROM golang:1.12-alpine AS base
+
+ARG PROJECT=github.com/docker/app
+ARG PROJECT_PATH=/go/src/${PROJECT}
+ENV CGO_ENABLED=0
+ENV PATH=${PATH}:${PROJECT_PATH}/build
+WORKDIR $PROJECT_PATH
+
+RUN mkdir -p docs/yaml/gen
+
+COPY . .
+RUN go build -o build/yaml-docs-generator ${PROJECT}/docs/yaml
+RUN build/yaml-docs-generator \
+  --root   "${PROJECT_PATH}" \
+  --target "${PROJECT_PATH}/docs/yaml/gen"
+
+
+FROM scratch
+ARG PROJECT=github.com/docker/app
+ARG PROJECT_PATH=/go/src/${PROJECT}
+ENV PROJECT_PATH=${PROJECT_PATH}
+# CMD cannot be nil so we set it to empty string
+CMD  [""]
+COPY --from=base ${PROJECT_PATH}/docs/reference /docs/reference
+COPY --from=base ${PROJECT_PATH}/docs/yaml/gen /docs/yaml

docs/yaml/Dockerfile

@@ -0,0 +1,107 @@
+package main
+
+import (
+	"fmt"
+	"io/ioutil"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/docker/app/internal/commands"
+	clicommand "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 := clicommand.NewDockerCli()
+	if err != nil {
+		return err
+	}
+	cmd := &cobra.Command{Use: "docker"}
+	cmd.AddCommand(commands.NewRootCmd("app", dockerCLI))
+	disableFlagsInUseLine(cmd)
+	source := filepath.Join(opts.source, descriptionSourcePath)
+	if err := loadLongDescription(cmd, source); err != nil {
+		return err
+	}
+
+	cmd.DisableAutoGenTag = true
+	return 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(cmd *cobra.Command, path ...string) error {
+	for _, cmd := range cmd.Commands() {
+		if cmd.Name() == "" {
+			continue
+		}
+		fullpath := filepath.Join(path[0], strings.Join(append(path[1:], cmd.Name()), "_")+".md")
+
+		if cmd.HasSubCommands() {
+			if err := loadLongDescription(cmd, path[0], cmd.Name()); err != nil {
+				return err
+			}
+		}
+
+		if _, err := os.Stat(fullpath); err != nil {
+			log.Printf("WARN: %s does not exist, skipping\n", fullpath)
+			continue
+		}
+
+		content, err := ioutil.ReadFile(fullpath)
+		if err != nil {
+			return err
+		}
+		description, examples := parseMDContent(string(content))
+		cmd.Long = description
+		cmd.Example = examples
+	}
+	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 {
+		fmt.Fprintln(os.Stderr, err.Error())
+	}
+	fmt.Printf("Project root: %s\n", opts.source)
+	fmt.Printf("Generating yaml files into %s\n", opts.target)
+	if err := generateCliYaml(opts); err != nil {
+		fmt.Fprintf(os.Stderr, "Failed to generate yaml files: %s\n", err.Error())
+	}
+}