add generator

Author: ArthurFlag

Dockerfile

@@ -1,6 +1,8 @@
 #syntax=docker/dockerfile:1
 
 ARG GO_VERSION=1.24.4
+ARG ALPINE_VERSION=3.21
+ARG DOCS_FORMATS="md,yaml"
 
 FROM --platform=${BUILDPLATFORM} golangci/golangci-lint:v2.1.6-alpine AS lint-base
 
@@ -129,3 +131,45 @@ EOF
 RUN chmod +x /run.sh
 ENV PORT=8080
 ENTRYPOINT ["/run.sh"]
+
+FROM --platform=${BUILDPLATFORM} golang:${GO_VERSION}-alpine${ALPINE_VERSION} AS alpine
+RUN apk add --no-cache rsync git
+ENV CGO_ENABLED=0
+WORKDIR /src
+
+FROM alpine AS docs-gen
+WORKDIR /src
+RUN --mount=target=. \
+    --mount=target=/root/.cache,type=cache \
+    go build -mod=vendor -o /out/docsgen ./docs/generator/generate.go
+
+FROM alpine AS docs-build
+COPY --from=docs-gen /out/docsgen /usr/bin
+ENV DOCKER_CLI_PLUGIN_ORIGINAL_CLI_COMMAND="mcp"
+ARG DOCS_FORMATS
+RUN --mount=target=/context \
+    --mount=target=.,type=tmpfs <<EOT
+  set -e
+  rsync -a /context/. .
+  docsgen --formats "$DOCS_FORMATS" --source "docs/generator/reference"
+  mkdir /out
+  cp -r docs/generator/reference/* /out/
+EOT
+
+FROM scratch AS docs-update
+COPY --from=docs-build /out /
+
+FROM docs-build AS docs-validate
+RUN --mount=target=/context \
+    --mount=target=.,type=tmpfs <<EOT
+  set -e
+  rsync -a /context/. .
+  git add -A
+  rm -rf docs/generator/reference/*
+  cp -rf /out/* ./docs/generator/reference/
+  if [ -n "$(git status --porcelain -- docs/generator/reference)" ]; then
+    echo >&2 'ERROR: Docs result differs. Please update with "make docs"'
+    git status --porcelain -- docs/generator/reference
+    exit 1
+  fi
+EOT

Makefile

@@ -34,6 +34,13 @@ docker-mcp-cross:
 docker-mcp-%:
 	docker buildx build $(DOCKER_BUILD_ARGS) --target=package-docker-mcp --platform=$*/amd64,$*/arm64 -o ./dist .
 
+docs:
+	$(eval $@_TMP_OUT := $(shell mktemp -d -t mcp-cli-output.XXXXXXXXXX))
+	docker buildx bake --set "*.output=type=local,dest=$($@_TMP_OUT)" update-docs
+	rm -rf ./docs/generator/reference/*
+	cp -R "$($@_TMP_OUT)"/* ./docs/generator/reference/
+	rm -rf "$($@_TMP_OUT)"/*
+
 push-module-image:
 	cp -r dist ./module-image
 	docker buildx build --push --platform=linux/amd64,linux/arm64,darwin/amd64,darwin/arm64,windows/amd64,windows/arm64 --build-arg TAG=$(TAG) --tag=docker/docker-mcp-cli-desktop-module:$(TAG) ./module-image
@@ -70,4 +77,4 @@ push-l7proxy-image:
 push-dns-forwarder-image:
 	docker buildx bake dns-forwarder --push
 
-.PHONY: format lint clean docker-mcp-cross push-module-image mcp-package test docker-mcp push-mcp-gateway push-l4proxy-image push-l7proxy-image push-dns-forwarder-image
+.PHONY: format lint clean docker-mcp-cross push-module-image mcp-package test docker-mcp push-mcp-gateway push-l4proxy-image push-l7proxy-image push-dns-forwarder-image docs

docker-bake.hcl

@@ -1,3 +1,17 @@
+variable "GO_VERSION" {
+  default = null
+}
+
+target "_common" {
+  args = {
+    GO_VERSION = GO_VERSION
+    BUILDKIT_CONTEXT_KEEP_GIT_DIR = 1
+  }
+}
+
+variable "DOCS_FORMATS" {
+  default = "md,yaml"
+}
 
 group default {
   targets = [
@@ -13,6 +27,7 @@ group all {
     "l4proxy",
     "l7proxy",
     "dns-forwarder",
+    "validate-docs",
   ]
 }
 
@@ -76,4 +91,22 @@ target mcp-gateway-dind {
   output = [
     "type=image,name=docker/mcp-gateway:dind",
   ]
+}
+
+target "validate-docs" {
+  inherits = ["_common"]
+  args = {
+    DOCS_FORMATS = DOCS_FORMATS
+  }
+  target = "docs-validate"
+  output = ["type=cacheonly"]
+}
+
+target "update-docs" {
+  inherits = ["_common"]
+  args = {
+    DOCS_FORMATS = DOCS_FORMATS
+  }
+  target = "docs-update"
+  output = ["./docs/generator/reference"]
 }

docs/generator/generate.go

@@ -0,0 +1,107 @@
+package main
+
+import (
+	"log"
+	"os"
+	"strings"
+
+	clidocstool "github.com/docker/cli-docs-tool"
+	"github.com/docker/cli/cli/command"
+	"github.com/docker/mcp-gateway/cmd/docker-mcp"
+	"github.com/pkg/errors"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+const defaultSourcePath = "/reference/"
+
+type options struct {
+	source  string
+	formats []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.",
+		DisableAutoGenTag: true,
+	}
+
+	cmd.AddCommand(commands.NewRootCmd(dockerCLI))
+
+	c, err := clidocstool.New(clidocstool.Options{
+		Root:      cmd,
+		SourceDir: opts.source,
+		Plugin:    true,
+	})
+	if err != nil {
+		return err
+	}
+
+	for _, format := range opts.formats {
+		switch format {
+		case "md":
+			if err = c.GenMarkdownTree(cmd); err != nil {
+				return err
+			}
+		case "yaml":
+			fixUpExperimentalCLI(cmd)
+			if err = c.GenYamlTree(cmd); err != nil {
+				return err
+			}
+		default:
+			return errors.Errorf("unknown format %q", format)
+		}
+	}
+
+	return nil
+}
+
+func run() error {
+	opts := &options{}
+	flags := pflag.NewFlagSet(os.Args[0], pflag.ContinueOnError)
+	flags.StringVar(&opts.source, "source", defaultSourcePath, "Docs source folder")
+	flags.StringSliceVar(&opts.formats, "formats", []string{}, "Format (md, yaml)")
+	if err := flags.Parse(os.Args[1:]); err != nil {
+		return err
+	}
+	if len(opts.formats) == 0 {
+		return errors.New("Docs format required")
+	}
+	return gen(opts)
+}
+
+func main() {
+	if err := run(); err != nil {
+		log.Printf("ERROR: %+v", err)
+		os.Exit(1)
+	}
+}
+
+// fixUpExperimentalCLI trims the " (EXPERIMENTAL)" suffix from the CLI output,
+// as docs.docker.com already displays "experimental (CLI)",
+//
+// https://github.com/docker/buildx/pull/2188#issuecomment-1889487022
+func fixUpExperimentalCLI(cmd *cobra.Command) {
+	const (
+		annotationExperimentalCLI = "experimentalCLI"
+		suffixExperimental        = " (EXPERIMENTAL)"
+	)
+	if _, ok := cmd.Annotations[annotationExperimentalCLI]; ok {
+		cmd.Short = strings.TrimSuffix(cmd.Short, suffixExperimental)
+	}
+	cmd.Flags().VisitAll(func(f *pflag.Flag) {
+		if _, ok := f.Annotations[annotationExperimentalCLI]; ok {
+			f.Usage = strings.TrimSuffix(f.Usage, suffixExperimental)
+		}
+	})
+	for _, c := range cmd.Commands() {
+		fixUpExperimentalCLI(c)
+	}
+}