generate reference docs with cli-docs-tool

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

Author: crazy-max

.github/workflows/validate.yml

@@ -0,0 +1,53 @@
+name: validate
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - 'main'
+      - 'v[0-9]*'
+    tags:
+      - 'v*'
+
+jobs:
+  prepare:
+    runs-on: ubuntu-24.04
+    outputs:
+      targets: ${{ steps.generate.outputs.targets }}
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+      -
+        name: List targets
+        id: generate
+        uses: docker/bake-action/subaction/list-targets@v6
+        with:
+          target: validate
+
+  validate:
+    runs-on: ubuntu-24.04
+    needs:
+      - prepare
+    strategy:
+      fail-fast: false
+      matrix:
+        target: ${{ fromJson(needs.prepare.outputs.targets) }}
+    steps:
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          buildkitd-flags: --debug
+      -
+        name: Validate
+        uses: docker/bake-action@v6
+        with:
+          targets: ${{ matrix.target }}

Dockerfile

@@ -0,0 +1,49 @@
+# syntax=docker/dockerfile:1
+
+ARG GO_VERSION=1.24
+ARG ALPINE_VERSION=3.21
+
+ARG DOCS_FORMATS="md,yaml"
+
+FROM --platform=${BUILDPLATFORM} golang:${GO_VERSION}-alpine${ALPINE_VERSION} AS base
+RUN apk add --no-cache rsync git
+ENV GOFLAGS=-mod=vendor
+ENV CGO_ENABLED=0
+WORKDIR /src
+
+FROM base AS docs-gen
+WORKDIR /src
+RUN --mount=target=. \
+    --mount=target=/root/.cache,type=cache \
+    go build -mod=vendor -o /out/docsgen ./docs/generate.go
+
+FROM base AS docs-build
+WORKDIR /src
+COPY --from=docs-gen /out/docsgen /usr/bin
+ARG DOCS_FORMATS
+RUN --mount=target=/context \
+    --mount=target=.,type=tmpfs <<EOT
+  set -e
+  rsync -a /context/. .
+  docsgen --formats "$DOCS_FORMATS" --source "docs/reference"
+  mkdir /out
+  cp -r docs/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/reference/*
+  cp -rf /out/* ./docs/reference/
+  if [ -n "$(git status --porcelain -- docs/reference)" ]; then
+    echo >&2 'ERROR: Docs result differs. Please update with "make docs"'
+    git status --porcelain -- docs/reference
+    exit 1
+  fi
+EOT

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all build clean link mock unit-tests
+.PHONY: all build clean link mock unit-tests docs
 
 BINARY_NAME=model-cli
 
@@ -67,3 +67,10 @@ clean:
 	@echo "Cleaning up..."
 	@rm -f $(BINARY_NAME)
 	@echo "Cleaned!"
+
+docs:
+	$(eval $@_TMP_OUT := $(shell mktemp -d -t model-cli-output.XXXXXXXXXX))
+	docker buildx bake --set "*.output=type=local,dest=$($@_TMP_OUT)" update-docs
+	rm -rf ./docs/reference/*
+	cp -R "$($@_TMP_OUT)"/* ./docs/reference/
+	rm -rf "$($@_TMP_OUT)"/*

docker-bake.hcl

@@ -0,0 +1,39 @@
+variable "GO_VERSION" {
+  default = null
+}
+variable "DOCS_FORMATS" {
+  default = "md,yaml"
+}
+
+target "_common" {
+  args = {
+    GO_VERSION = GO_VERSION
+    BUILDKIT_CONTEXT_KEEP_GIT_DIR = 1
+  }
+}
+
+group "default" {
+  targets = ["validate"]
+}
+
+group "validate" {
+  targets = ["validate-docs"]
+}
+
+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/reference"]
+}

docs/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/model-cli/commands"
+	"github.com/pkg/errors"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+const defaultSourcePath = "docs/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)
+	}
+}