docker/cli-0001-docs-include-required-tools-in-source-tree.patch

From 7d5055e48910d7c368d315c22c5b1603cee0aa1f Mon Sep 17 00:00:00 2001
From: danishprakash <danish.prakash@suse.com>
Date: Mon, 12 Feb 2024 18:07:06 +0530
Subject: [PATCH] [PATCH] docs: include required tools in source tree

In order to be able to build the documentation without internet access
(as is required by some distribution build systems), all of the source
code needed for the build needs to be available in the source tarball.

This used to be possible with the docker-cli sources but was
accidentally broken with some CI changes that switched to downloading
the tools (by modifying go.mod as part of the docs build script).

This pattern also maked documentation builds less reproducible since the
tool version used was not based on the source code version.

Fixes: commit 7dc35c03fca5 ("validate manpages target")
Fixes: commit a650f4ddd008 ("switch to cli-docs-tool for yaml docs generation")
Signed-off-by: Aleksa Sarai <asarai@suse.de>
---
 docs/generate/go.mod                          |   13 -
 docs/generate/tools.go                        |    8 -
 import.go                                     |   17 +
 man/tools.go                                  |   11 -
 scripts/docs/generate-man.sh                  |   33 +-
 scripts/docs/generate-md.sh                   |   36 +-
 scripts/docs/generate-yaml.sh                 |   29 +-
 vendor.mod                                    |    5 +
 vendor.sum                                    |    4 +
 .../cpuguy83/go-md2man/v2/.gitignore          |    2 +
 .../cpuguy83/go-md2man/v2/.golangci.yml       |    6 +
 .../cpuguy83/go-md2man/v2/Dockerfile          |   20 +
 .../cpuguy83/go-md2man/v2/LICENSE.md          |   21 +
 .../github.com/cpuguy83/go-md2man/v2/Makefile |   35 +
 .../cpuguy83/go-md2man/v2/README.md           |   15 +
 .../cpuguy83/go-md2man/v2/go-md2man.1.md      |   28 +
 .../cpuguy83/go-md2man/v2/md2man.go           |   53 +
 .../cpuguy83/go-md2man/v2/md2man/md2man.go    |   16 +
 .../cpuguy83/go-md2man/v2/md2man/roff.go      |  348 ++
 .../docker/cli-docs-tool/.dockerignore        |    2 +
 .../docker/cli-docs-tool/.gitignore           |    2 +
 .../docker/cli-docs-tool/.golangci.yml        |   37 +
 .../docker/cli-docs-tool/Dockerfile           |   86 +
 .../github.com/docker/cli-docs-tool/LICENSE   |  202 ++
 .../github.com/docker/cli-docs-tool/README.md |   67 +
 .../cli-docs-tool/annotation/annotation.go    |   25 +
 .../docker/cli-docs-tool/clidocstool.go       |  123 +
 .../docker/cli-docs-tool/clidocstool_md.go    |  280 ++
 .../docker/cli-docs-tool/clidocstool_yaml.go  |  435 +++
 .../docker/cli-docs-tool/docker-bake.hcl      |   51 +
 .../docker/cli-docs-tool/markdown.go          |   87 +
 .../russross/blackfriday/v2/.gitignore        |    8 +
 .../russross/blackfriday/v2/.travis.yml       |   17 +
 .../russross/blackfriday/v2/LICENSE.txt       |   29 +
 .../russross/blackfriday/v2/README.md         |  335 ++
 .../russross/blackfriday/v2/block.go          | 1612 +++++++++
 .../github.com/russross/blackfriday/v2/doc.go |   46 +
 .../russross/blackfriday/v2/entities.go       | 2236 ++++++++++++
 .../github.com/russross/blackfriday/v2/esc.go |   70 +
 .../russross/blackfriday/v2/html.go           |  952 ++++++
 .../russross/blackfriday/v2/inline.go         | 1228 +++++++
 .../russross/blackfriday/v2/markdown.go       |  950 ++++++
 .../russross/blackfriday/v2/node.go           |  360 ++
 .../russross/blackfriday/v2/smartypants.go    |  457 +++
 vendor/github.com/spf13/cobra/doc/man_docs.go |  246 ++
 vendor/github.com/spf13/cobra/doc/md_docs.go  |  158 +
 .../github.com/spf13/cobra/doc/rest_docs.go   |  186 +
 vendor/github.com/spf13/cobra/doc/util.go     |   52 +
 .../github.com/spf13/cobra/doc/yaml_docs.go   |  175 +
 vendor/gopkg.in/yaml.v3/LICENSE               |   50 +
 vendor/gopkg.in/yaml.v3/NOTICE                |   13 +
 vendor/gopkg.in/yaml.v3/README.md             |  150 +
 vendor/gopkg.in/yaml.v3/apic.go               |  747 ++++
 vendor/gopkg.in/yaml.v3/decode.go             | 1000 ++++++
 vendor/gopkg.in/yaml.v3/emitterc.go           | 2020 +++++++++++
 vendor/gopkg.in/yaml.v3/encode.go             |  577 ++++
 vendor/gopkg.in/yaml.v3/parserc.go            | 1258 +++++++
 vendor/gopkg.in/yaml.v3/readerc.go            |  434 +++
 vendor/gopkg.in/yaml.v3/resolve.go            |  326 ++
 vendor/gopkg.in/yaml.v3/scannerc.go           | 3038 +++++++++++++++++
 vendor/gopkg.in/yaml.v3/sorter.go             |  134 +
 vendor/gopkg.in/yaml.v3/writerc.go            |   48 +
 vendor/gopkg.in/yaml.v3/yaml.go               |  698 ++++
 vendor/gopkg.in/yaml.v3/yamlh.go              |  807 +++++
 vendor/gopkg.in/yaml.v3/yamlprivateh.go       |  198 ++
 vendor/modules.txt                            |   15 +
 66 files changed, 22631 insertions(+), 96 deletions(-)
 delete mode 100644 docs/generate/go.mod
 delete mode 100644 docs/generate/tools.go
 create mode 100644 import.go
 delete mode 100644 man/tools.go
 create mode 100644 vendor/github.com/cpuguy83/go-md2man/v2/.gitignore
 create mode 100644 vendor/github.com/cpuguy83/go-md2man/v2/.golangci.yml
 create mode 100644 vendor/github.com/cpuguy83/go-md2man/v2/Dockerfile
 create mode 100644 vendor/github.com/cpuguy83/go-md2man/v2/LICENSE.md
 create mode 100644 vendor/github.com/cpuguy83/go-md2man/v2/Makefile
 create mode 100644 vendor/github.com/cpuguy83/go-md2man/v2/README.md
 create mode 100644 vendor/github.com/cpuguy83/go-md2man/v2/go-md2man.1.md
 create mode 100644 vendor/github.com/cpuguy83/go-md2man/v2/md2man.go
 create mode 100644 vendor/github.com/cpuguy83/go-md2man/v2/md2man/md2man.go
 create mode 100644 vendor/github.com/cpuguy83/go-md2man/v2/md2man/roff.go
 create mode 100644 vendor/github.com/docker/cli-docs-tool/.dockerignore
 create mode 100644 vendor/github.com/docker/cli-docs-tool/.gitignore
 create mode 100644 vendor/github.com/docker/cli-docs-tool/.golangci.yml
 create mode 100644 vendor/github.com/docker/cli-docs-tool/Dockerfile
 create mode 100644 vendor/github.com/docker/cli-docs-tool/LICENSE
 create mode 100644 vendor/github.com/docker/cli-docs-tool/README.md
 create mode 100644 vendor/github.com/docker/cli-docs-tool/annotation/annotation.go
 create mode 100644 vendor/github.com/docker/cli-docs-tool/clidocstool.go
 create mode 100644 vendor/github.com/docker/cli-docs-tool/clidocstool_md.go
 create mode 100644 vendor/github.com/docker/cli-docs-tool/clidocstool_yaml.go
 create mode 100644 vendor/github.com/docker/cli-docs-tool/docker-bake.hcl
 create mode 100644 vendor/github.com/docker/cli-docs-tool/markdown.go
 create mode 100644 vendor/github.com/russross/blackfriday/v2/.gitignore
 create mode 100644 vendor/github.com/russross/blackfriday/v2/.travis.yml
 create mode 100644 vendor/github.com/russross/blackfriday/v2/LICENSE.txt
 create mode 100644 vendor/github.com/russross/blackfriday/v2/README.md
 create mode 100644 vendor/github.com/russross/blackfriday/v2/block.go
 create mode 100644 vendor/github.com/russross/blackfriday/v2/doc.go
 create mode 100644 vendor/github.com/russross/blackfriday/v2/entities.go
 create mode 100644 vendor/github.com/russross/blackfriday/v2/esc.go
 create mode 100644 vendor/github.com/russross/blackfriday/v2/html.go
 create mode 100644 vendor/github.com/russross/blackfriday/v2/inline.go
 create mode 100644 vendor/github.com/russross/blackfriday/v2/markdown.go
 create mode 100644 vendor/github.com/russross/blackfriday/v2/node.go
 create mode 100644 vendor/github.com/russross/blackfriday/v2/smartypants.go
 create mode 100644 vendor/github.com/spf13/cobra/doc/man_docs.go
 create mode 100644 vendor/github.com/spf13/cobra/doc/md_docs.go
 create mode 100644 vendor/github.com/spf13/cobra/doc/rest_docs.go
 create mode 100644 vendor/github.com/spf13/cobra/doc/util.go
 create mode 100644 vendor/github.com/spf13/cobra/doc/yaml_docs.go
 create mode 100644 vendor/gopkg.in/yaml.v3/LICENSE
 create mode 100644 vendor/gopkg.in/yaml.v3/NOTICE
 create mode 100644 vendor/gopkg.in/yaml.v3/README.md
 create mode 100644 vendor/gopkg.in/yaml.v3/apic.go
 create mode 100644 vendor/gopkg.in/yaml.v3/decode.go
 create mode 100644 vendor/gopkg.in/yaml.v3/emitterc.go
 create mode 100644 vendor/gopkg.in/yaml.v3/encode.go
 create mode 100644 vendor/gopkg.in/yaml.v3/parserc.go
 create mode 100644 vendor/gopkg.in/yaml.v3/readerc.go
 create mode 100644 vendor/gopkg.in/yaml.v3/resolve.go
 create mode 100644 vendor/gopkg.in/yaml.v3/scannerc.go
 create mode 100644 vendor/gopkg.in/yaml.v3/sorter.go
 create mode 100644 vendor/gopkg.in/yaml.v3/writerc.go
 create mode 100644 vendor/gopkg.in/yaml.v3/yaml.go
 create mode 100644 vendor/gopkg.in/yaml.v3/yamlh.go
 create mode 100644 vendor/gopkg.in/yaml.v3/yamlprivateh.go

diff --git a/docs/generate/go.mod b/docs/generate/go.mod
deleted file mode 100644
index d62ff455713a..000000000000
--- a/docs/generate/go.mod
+++ /dev/null
@@ -1,13 +0,0 @@
-module github.com/docker/cli/docs/generate
-
-// 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.5.0
-//)
-//
-//replace github.com/docker/cli v0.0.0+incompatible => ../../
diff --git a/docs/generate/tools.go b/docs/generate/tools.go
deleted file mode 100644
index 47510bc49a89..000000000000
--- a/docs/generate/tools.go
+++ /dev/null
@@ -1,8 +0,0 @@
-//go:build tools
-// +build tools
-
-package main
-
-import (
-	_ "github.com/docker/cli-docs-tool"
-)
diff --git a/import.go b/import.go
new file mode 100644
index 000000000000..662a6055146c
--- /dev/null
+++ b/import.go
@@ -0,0 +1,17 @@
+// This is only used to define imports we need for doc generation.
+
+//go:build never
+// +build never
+
+package cli
+
+import (
+	// Used for md and yaml doc generation.
+	_ "github.com/docker/cli-docs-tool"
+
+	// Used for man page generation.
+	_ "github.com/cpuguy83/go-md2man/v2"
+	_ "github.com/spf13/cobra"
+	_ "github.com/spf13/cobra/doc"
+	_ "github.com/spf13/pflag"
+)
diff --git a/man/tools.go b/man/tools.go
deleted file mode 100644
index 3cafe6533aff..000000000000
--- a/man/tools.go
+++ /dev/null
@@ -1,11 +0,0 @@
-//go:build tools
-// +build tools
-
-package main
-
-import (
-	_ "github.com/cpuguy83/go-md2man/v2"
-	_ "github.com/spf13/cobra"
-	_ "github.com/spf13/cobra/doc"
-	_ "github.com/spf13/pflag"
-)
diff --git a/scripts/docs/generate-man.sh b/scripts/docs/generate-man.sh
index 12a4b81199db..1e12a95e9c9a 100755
--- a/scripts/docs/generate-man.sh
+++ b/scripts/docs/generate-man.sh
@@ -1,35 +1,22 @@
 #!/usr/bin/env bash
 
-set -eu
-
-: "${MD2MAN_VERSION=v2.0.3}"
+set -Eeuo pipefail
 
 export GO111MODULE=auto
 
-function clean {
-  rm -rf "$buildir"
+# temporary "go.mod" to make -modfile= work
+touch go.mod
+
+function clean() {
+  rm -f "$(pwd)/go.mod"
 }
 
-buildir=$(mktemp -d -t docker-cli-docsgen.XXXXXXXXXX)
 trap clean EXIT
 
-(
-  set -x
-  cp -r . "$buildir/"
-  cd "$buildir"
-  # init dummy go.mod
-  ./scripts/vendor init
-  # install go-md2man and copy man/tools.go in root folder
-  # to be able to fetch the required dependencies
-  go mod edit -modfile=vendor.mod -require=github.com/cpuguy83/go-md2man/v2@${MD2MAN_VERSION}
-  cp man/tools.go .
-  # update vendor
-  ./scripts/vendor update
-  # build gen-manpages
-  go build -mod=vendor -modfile=vendor.mod -tags manpages -o /tmp/gen-manpages ./man/generate.go
-  # build go-md2man
-  go build -mod=vendor -modfile=vendor.mod -o /tmp/go-md2man ./vendor/github.com/cpuguy83/go-md2man/v2
-)
+# build gen-manpages
+go build -mod=vendor -modfile=vendor.mod -tags manpages -o /tmp/gen-manpages ./man/generate.go
+# build go-md2man
+go build -mod=vendor -modfile=vendor.mod -o /tmp/go-md2man ./vendor/github.com/cpuguy83/go-md2man/v2
 
 mkdir -p man/man1
 (set -x ; /tmp/gen-manpages --root "." --target "$(pwd)/man/man1")
diff --git a/scripts/docs/generate-md.sh b/scripts/docs/generate-md.sh
index 4caa01eaed23..0af86843bbe4 100755
--- a/scripts/docs/generate-md.sh
+++ b/scripts/docs/generate-md.sh
@@ -1,33 +1,29 @@
 #!/usr/bin/env bash
 
-set -eu
-
-: "${CLI_DOCS_TOOL_VERSION=v0.7.0}"
+set -Eeuo pipefail
 
 export GO111MODULE=auto
 
+# temporary "go.mod" to make -modfile= work
+touch go.mod
+
 function clean {
-  rm -rf "$buildir"
+  rm -f "$(pwd)/go.mod"
+  if [ -f "$(pwd)/docs/reference/commandline/docker.md" ]; then
+    mv "$(pwd)/docs/reference/commandline/docker.md" "$(pwd)/docs/reference/commandline/cli.md"
+  fi
 }
 
-buildir=$(mktemp -d -t docker-cli-docsgen.XXXXXXXXXX)
 trap clean EXIT
 
-(
-  set -x
-  cp -r . "$buildir/"
-  cd "$buildir"
-  # init dummy go.mod
-  ./scripts/vendor init
-  # install cli-docs-tool and copy docs/tools.go in root folder
-  # to be able to fetch the required depedencies
-  go mod edit -modfile=vendor.mod -require=github.com/docker/cli-docs-tool@${CLI_DOCS_TOOL_VERSION}
-  cp docs/generate/tools.go .
-  # update vendor
-  ./scripts/vendor update
-  # build docsgen
-  go build -mod=vendor -modfile=vendor.mod -tags docsgen -o /tmp/docsgen ./docs/generate/generate.go
-)
+# build docsgen
+go build -mod=vendor -modfile=vendor.mod -tags docsgen -o /tmp/docsgen ./docs/generate/generate.go
+
+# yaml generation on docs repo needs the cli.md file: https://github.com/docker/cli/pull/3924#discussion_r1059986605
+# but markdown generation docker.md atm. While waiting for a fix in cli-docs-tool
+# we need to first move the cli.md file to docker.md, do the generation and
+# then move it back in trap handler.
+mv "$(pwd)/docs/reference/commandline/cli.md" "$(pwd)/docs/reference/commandline/docker.md"
 
 (
   set -x
diff --git a/scripts/docs/generate-yaml.sh b/scripts/docs/generate-yaml.sh
index 0d67c5e5bb09..7d98e161df5d 100755
--- a/scripts/docs/generate-yaml.sh
+++ b/scripts/docs/generate-yaml.sh
@@ -1,33 +1,20 @@
 #!/usr/bin/env bash
 
-set -eu
-
-: "${CLI_DOCS_TOOL_VERSION=v0.7.0}"
+set -Eeuo pipefail
 
 export GO111MODULE=auto
 
-function clean {
-  rm -rf "$buildir"
+# temporary "go.mod" to make -modfile= work
+touch go.mod
+
+function clean() {
+  rm -f "$(pwd)/go.mod"
 }
 
-buildir=$(mktemp -d -t docker-cli-docsgen.XXXXXXXXXX)
 trap clean EXIT
 
-(
-  set -x
-  cp -r . "$buildir/"
-  cd "$buildir"
-  # init dummy go.mod
-  ./scripts/vendor init
-  # install cli-docs-tool and copy docs/tools.go in root folder
-  # to be able to fetch the required depedencies
-  go mod edit -modfile=vendor.mod -require=github.com/docker/cli-docs-tool@${CLI_DOCS_TOOL_VERSION}
-  cp docs/generate/tools.go .
-  # update vendor
-  ./scripts/vendor update
-  # build docsgen
-  go build -mod=vendor -modfile=vendor.mod -tags docsgen -o /tmp/docsgen ./docs/generate/generate.go
-)
+# build docsgen
+go build -mod=vendor -modfile=vendor.mod -tags docsgen -o /tmp/docsgen ./docs/generate/generate.go
 
 mkdir -p docs/yaml
 set -x
diff --git a/vendor.mod b/vendor.mod
index cb538723603a..ba34bb097a32 100644
--- a/vendor.mod
+++ b/vendor.mod
@@ -11,6 +11,7 @@ require (
 	github.com/containerd/containerd v1.7.12
 	github.com/creack/pty v1.1.21
 	github.com/distribution/reference v0.5.0
+	github.com/docker/cli-docs-tool v0.6.0
 	github.com/docker/distribution v2.8.3+incompatible
 	github.com/docker/docker v25.0.5-0.20240319141229-e63daec8672d+incompatible // 25.0 branch (v25.0.5-dev)
 	github.com/docker/docker-credential-helpers v0.8.1
@@ -46,6 +47,8 @@ require (
 	tags.cncf.io/container-device-interface v0.6.2
 )
 
+require github.com/cpuguy83/go-md2man/v2 v2.0.3
+
 require (
 	github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
 	github.com/Microsoft/go-winio v0.6.1 // indirect
@@ -72,6 +75,7 @@ require (
 	github.com/prometheus/common v0.42.0 // indirect
 	github.com/prometheus/procfs v0.9.0 // indirect
 	github.com/rivo/uniseg v0.2.0 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb // indirect
 	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
 	go.etcd.io/etcd/raft/v3 v3.5.6 // indirect
@@ -87,4 +91,5 @@ require (
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20230711160842-782d3b101e98 // indirect
 	google.golang.org/grpc v1.58.3 // indirect
 	google.golang.org/protobuf v1.31.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
diff --git a/vendor.sum b/vendor.sum
index 064239b2fa8f..ca83ab55f00a 100644
--- a/vendor.sum
+++ b/vendor.sum
@@ -41,6 +41,7 @@ github.com/containerd/containerd v1.7.12/go.mod h1:/5OMpE1p0ylxtEUGY8kuCYkDRzJm9
 github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
 github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
 github.com/coreos/go-systemd/v22 v22.3.2/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
+github.com/cpuguy83/go-md2man/v2 v2.0.3 h1:qMCsGGgs+MAzDFyp9LpAe1Lqy/fY/qCovCm0qnXZOBM=
 github.com/cpuguy83/go-md2man/v2 v2.0.3/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/creack/pty v1.1.21 h1:1/QdRyBaHHJP61QkWMXlOIBfsgdDeeKfK8SYVUWJKf0=
@@ -51,6 +52,8 @@ github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
 github.com/denisenkom/go-mssqldb v0.0.0-20191128021309-1d7a30a10f73/go.mod h1:xbL0rPBG9cCiLr28tMa8zpbdarY27NDyej4t/EjAShU=
 github.com/distribution/reference v0.5.0 h1:/FUIFXtfc/x2gpa5/VGfiGLuOIdYa1t65IKK2OFGvA0=
 github.com/distribution/reference v0.5.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
+github.com/docker/cli-docs-tool v0.6.0 h1:Z9x10SaZgFaB6jHgz3OWooynhSa40CsWkpe5hEnG/qA=
+github.com/docker/cli-docs-tool v0.6.0/go.mod h1:zMjqTFCU361PRh8apiXzeAZ1Q/xupbIwTusYpzCXS/o=
 github.com/docker/distribution v2.7.1+incompatible/go.mod h1:J2gT2udsDAN96Uj4KfcMRqY0/ypR+oyYUYmja8H+y+w=
 github.com/docker/distribution v2.8.3+incompatible h1:AtKxIZ36LoNK51+Z6RpzLpddBirtxJnzDrHLEKxTAYk=
 github.com/docker/distribution v2.8.3+incompatible/go.mod h1:J2gT2udsDAN96Uj4KfcMRqY0/ypR+oyYUYmja8H+y+w=
@@ -227,6 +230,7 @@ github.com/prometheus/procfs v0.9.0 h1:wzCHvIvM5SxWqYvwgVL7yJY8Lz3PKn49KQtpgMYJf
 github.com/prometheus/procfs v0.9.0/go.mod h1:+pB4zwohETzFnmlpe6yd2lSc+0/46IYZRB/chUwxUZY=
 github.com/rivo/uniseg v0.2.0 h1:S1pD9weZBuJdFmowNwbpi7BJ8TNftyUImj/0WQi72jY=
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sirupsen/logrus v1.0.6/go.mod h1:pMByvHTf9Beacp5x1UXfOR9xyW/9antXMhjMPG0dEzc=
 github.com/sirupsen/logrus v1.2.0/go.mod h1:LxeOpSwHxABJmUn/MG1IvRgCAasNZTLOkJPxbbu5VWo=
diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/.gitignore b/vendor/github.com/cpuguy83/go-md2man/v2/.gitignore
new file mode 100644
index 000000000000..30f97c3d73ab
--- /dev/null
+++ b/vendor/github.com/cpuguy83/go-md2man/v2/.gitignore
@@ -0,0 +1,2 @@
+go-md2man
+bin
diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/.golangci.yml b/vendor/github.com/cpuguy83/go-md2man/v2/.golangci.yml
new file mode 100644
index 000000000000..71f073f3c6b9
--- /dev/null
+++ b/vendor/github.com/cpuguy83/go-md2man/v2/.golangci.yml
@@ -0,0 +1,6 @@
+# For documentation, see https://golangci-lint.run/usage/configuration/
+
+linters:
+  enable:
+    - gofumpt
+
diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/Dockerfile b/vendor/github.com/cpuguy83/go-md2man/v2/Dockerfile
new file mode 100644
index 000000000000..7181c5306f41
--- /dev/null
+++ b/vendor/github.com/cpuguy83/go-md2man/v2/Dockerfile
@@ -0,0 +1,20 @@
+ARG GO_VERSION=1.18
+ARG GO_IMAGE=golang:${GO_VERSION}
+
+FROM --platform=$BUILDPLATFORM $GO_IMAGE AS build
+COPY . /go/src/github.com/cpuguy83/go-md2man
+WORKDIR /go/src/github.com/cpuguy83/go-md2man
+ARG TARGETOS
+ARG TARGETARCH
+ARG TARGETVARIANT
+RUN \
+    export GOOS="${TARGETOS}"; \
+    export GOARCH="${TARGETARCH}"; \
+    if [ "${TARGETARCH}" = "arm" ] && [ "${TARGETVARIANT}" ]; then \
+    export GOARM="${TARGETVARIANT#v}"; \
+    fi; \
+    CGO_ENABLED=0 go build
+
+FROM scratch
+COPY --from=build /go/src/github.com/cpuguy83/go-md2man/go-md2man /go-md2man
+ENTRYPOINT ["/go-md2man"]
diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/LICENSE.md b/vendor/github.com/cpuguy83/go-md2man/v2/LICENSE.md
new file mode 100644
index 000000000000..1cade6cef6a1
--- /dev/null
+++ b/vendor/github.com/cpuguy83/go-md2man/v2/LICENSE.md
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Brian Goff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/Makefile b/vendor/github.com/cpuguy83/go-md2man/v2/Makefile
new file mode 100644
index 000000000000..437fc9997926
--- /dev/null
+++ b/vendor/github.com/cpuguy83/go-md2man/v2/Makefile
@@ -0,0 +1,35 @@
+GO111MODULE ?= on
+LINTER_BIN ?= golangci-lint
+
+export GO111MODULE
+
+.PHONY:
+build: bin/go-md2man
+
+.PHONY: clean
+clean:
+	@rm -rf bin/*
+
+.PHONY: test
+test:
+	@go test $(TEST_FLAGS) ./...
+
+bin/go-md2man: actual_build_flags := $(BUILD_FLAGS) -o bin/go-md2man
+bin/go-md2man: bin
+	@CGO_ENABLED=0 go build $(actual_build_flags)
+
+bin:
+	@mkdir ./bin
+
+.PHONY: mod
+mod:
+	@go mod tidy
+
+.PHONY: check-mod
+check-mod: # verifies that module changes for go.mod and go.sum are checked in
+	@hack/ci/check_mods.sh
+
+.PHONY: vendor
+vendor: mod
+	@go mod vendor -v
+
diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/README.md b/vendor/github.com/cpuguy83/go-md2man/v2/README.md
new file mode 100644
index 000000000000..0e30d341483c
--- /dev/null
+++ b/vendor/github.com/cpuguy83/go-md2man/v2/README.md
@@ -0,0 +1,15 @@
+go-md2man
+=========
+
+Converts markdown into roff (man pages).
+
+Uses blackfriday to process markdown into man pages.
+
+### Usage
+
+./md2man -in /path/to/markdownfile.md -out /manfile/output/path
+
+### How to contribute
+
+We use go modules to manage dependencies.
+As such you must be using at lest go1.11.
diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/go-md2man.1.md b/vendor/github.com/cpuguy83/go-md2man/v2/go-md2man.1.md
new file mode 100644
index 000000000000..aa4587e279ff
--- /dev/null
+++ b/vendor/github.com/cpuguy83/go-md2man/v2/go-md2man.1.md
@@ -0,0 +1,28 @@
+go-md2man 1 "January 2015" go-md2man "User Manual"
+==================================================
+
+# NAME
+go-md2man - Convert markdown files into manpages
+
+# SYNOPSIS
+**go-md2man** [**-in**=*/path/to/md/file*] [**-out**=*/path/to/output*]
+
+# DESCRIPTION
+**go-md2man** converts standard markdown formatted documents into manpages. It is
+written purely in Go so as to reduce dependencies on 3rd party libs.
+
+By default, the input is stdin and the output is stdout.
+
+# EXAMPLES
+Convert the markdown file *go-md2man.1.md* into a manpage:
+```
+go-md2man < go-md2man.1.md > go-md2man.1
+```
+
+Same, but using command line arguments instead of shell redirection:
+```
+go-md2man -in=go-md2man.1.md -out=go-md2man.1
+```
+
+# HISTORY
+January 2015, Originally compiled by Brian Goff (cpuguy83@gmail.com).
diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/md2man.go b/vendor/github.com/cpuguy83/go-md2man/v2/md2man.go
new file mode 100644
index 000000000000..4ff873b8e767
--- /dev/null
+++ b/vendor/github.com/cpuguy83/go-md2man/v2/md2man.go
@@ -0,0 +1,53 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"io/ioutil"
+	"os"
+
+	"github.com/cpuguy83/go-md2man/v2/md2man"
+)
+
+var (
+	inFilePath  = flag.String("in", "", "Path to file to be processed (default: stdin)")
+	outFilePath = flag.String("out", "", "Path to output processed file (default: stdout)")
+)
+
+func main() {
+	var err error
+	flag.Parse()
+
+	inFile := os.Stdin
+	if *inFilePath != "" {
+		inFile, err = os.Open(*inFilePath)
+		if err != nil {
+			fmt.Println(err)
+			os.Exit(1)
+		}
+	}
+	defer inFile.Close() // nolint: errcheck
+
+	doc, err := ioutil.ReadAll(inFile)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+
+	out := md2man.Render(doc)
+
+	outFile := os.Stdout
+	if *outFilePath != "" {
+		outFile, err = os.Create(*outFilePath)
+		if err != nil {
+			fmt.Println(err)
+			os.Exit(1)
+		}
+		defer outFile.Close() // nolint: errcheck
+	}
+	_, err = outFile.Write(out)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+}
diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/md2man/md2man.go b/vendor/github.com/cpuguy83/go-md2man/v2/md2man/md2man.go
new file mode 100644
index 000000000000..42bf32aab003
--- /dev/null
+++ b/vendor/github.com/cpuguy83/go-md2man/v2/md2man/md2man.go
@@ -0,0 +1,16 @@
+package md2man
+
+import (
+	"github.com/russross/blackfriday/v2"
+)
+
+// Render converts a markdown document into a roff formatted document.
+func Render(doc []byte) []byte {
+	renderer := NewRoffRenderer()
+
+	return blackfriday.Run(doc,
+		[]blackfriday.Option{
+			blackfriday.WithRenderer(renderer),
+			blackfriday.WithExtensions(renderer.GetExtensions()),
+		}...)
+}
diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/md2man/roff.go b/vendor/github.com/cpuguy83/go-md2man/v2/md2man/roff.go
new file mode 100644
index 000000000000..4b19188d90fd
--- /dev/null
+++ b/vendor/github.com/cpuguy83/go-md2man/v2/md2man/roff.go
@@ -0,0 +1,348 @@
+package md2man
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/russross/blackfriday/v2"
+)
+
+// roffRenderer implements the blackfriday.Renderer interface for creating
+// roff format (manpages) from markdown text
+type roffRenderer struct {
+	extensions   blackfriday.Extensions
+	listCounters []int
+	firstHeader  bool
+	firstDD      bool
+	listDepth    int
+}
+
+const (
+	titleHeader      = ".TH "
+	topLevelHeader   = "\n\n.SH "
+	secondLevelHdr   = "\n.SH "
+	otherHeader      = "\n.SS "
+	crTag            = "\n"
+	emphTag          = "\\fI"
+	emphCloseTag     = "\\fP"
+	strongTag        = "\\fB"
+	strongCloseTag   = "\\fP"
+	breakTag         = "\n.br\n"
+	paraTag          = "\n.PP\n"
+	hruleTag         = "\n.ti 0\n\\l'\\n(.lu'\n"
+	linkTag          = "\n\\[la]"
+	linkCloseTag     = "\\[ra]"
+	codespanTag      = "\\fB"
+	codespanCloseTag = "\\fR"
+	codeTag          = "\n.EX\n"
+	codeCloseTag     = "\n.EE\n"
+	quoteTag         = "\n.PP\n.RS\n"
+	quoteCloseTag    = "\n.RE\n"
+	listTag          = "\n.RS\n"
+	listCloseTag     = "\n.RE\n"
+	dtTag            = "\n.TP\n"
+	dd2Tag           = "\n"
+	tableStart       = "\n.TS\nallbox;\n"
+	tableEnd         = ".TE\n"
+	tableCellStart   = "T{\n"
+	tableCellEnd     = "\nT}\n"
+)
+
+// NewRoffRenderer creates a new blackfriday Renderer for generating roff documents
+// from markdown
+func NewRoffRenderer() *roffRenderer { // nolint: golint
+	var extensions blackfriday.Extensions
+
+	extensions |= blackfriday.NoIntraEmphasis
+	extensions |= blackfriday.Tables
+	extensions |= blackfriday.FencedCode
+	extensions |= blackfriday.SpaceHeadings
+	extensions |= blackfriday.Footnotes
+	extensions |= blackfriday.Titleblock
+	extensions |= blackfriday.DefinitionLists
+	return &roffRenderer{
+		extensions: extensions,
+	}
+}
+
+// GetExtensions returns the list of extensions used by this renderer implementation
+func (r *roffRenderer) GetExtensions() blackfriday.Extensions {
+	return r.extensions
+}
+
+// RenderHeader handles outputting the header at document start
+func (r *roffRenderer) RenderHeader(w io.Writer, ast *blackfriday.Node) {
+	// disable hyphenation
+	out(w, ".nh\n")
+}
+
+// RenderFooter handles outputting the footer at the document end; the roff
+// renderer has no footer information
+func (r *roffRenderer) RenderFooter(w io.Writer, ast *blackfriday.Node) {
+}
+
+// RenderNode is called for each node in a markdown document; based on the node
+// type the equivalent roff output is sent to the writer
+func (r *roffRenderer) RenderNode(w io.Writer, node *blackfriday.Node, entering bool) blackfriday.WalkStatus {
+	walkAction := blackfriday.GoToNext
+
+	switch node.Type {
+	case blackfriday.Text:
+		escapeSpecialChars(w, node.Literal)
+	case blackfriday.Softbreak:
+		out(w, crTag)
+	case blackfriday.Hardbreak:
+		out(w, breakTag)
+	case blackfriday.Emph:
+		if entering {
+			out(w, emphTag)
+		} else {
+			out(w, emphCloseTag)
+		}
+	case blackfriday.Strong:
+		if entering {
+			out(w, strongTag)
+		} else {
+			out(w, strongCloseTag)
+		}
+	case blackfriday.Link:
+		// Don't render the link text for automatic links, because this
+		// will only duplicate the URL in the roff output.
+		// See https://daringfireball.net/projects/markdown/syntax#autolink
+		if !bytes.Equal(node.LinkData.Destination, node.FirstChild.Literal) {
+			out(w, string(node.FirstChild.Literal))
+		}
+		// Hyphens in a link must be escaped to avoid word-wrap in the rendered man page.
+		escapedLink := strings.ReplaceAll(string(node.LinkData.Destination), "-", "\\-")
+		out(w, linkTag+escapedLink+linkCloseTag)
+		walkAction = blackfriday.SkipChildren
+	case blackfriday.Image:
+		// ignore images
+		walkAction = blackfriday.SkipChildren
+	case blackfriday.Code:
+		out(w, codespanTag)
+		escapeSpecialChars(w, node.Literal)
+		out(w, codespanCloseTag)
+	case blackfriday.Document:
+		break
+	case blackfriday.Paragraph:
+		// roff .PP markers break lists
+		if r.listDepth > 0 {
+			return blackfriday.GoToNext
+		}
+		if entering {
+			out(w, paraTag)
+		} else {
+			out(w, crTag)
+		}
+	case blackfriday.BlockQuote:
+		if entering {
+			out(w, quoteTag)
+		} else {
+			out(w, quoteCloseTag)
+		}
+	case blackfriday.Heading:
+		r.handleHeading(w, node, entering)
+	case blackfriday.HorizontalRule:
+		out(w, hruleTag)
+	case blackfriday.List:
+		r.handleList(w, node, entering)
+	case blackfriday.Item:
+		r.handleItem(w, node, entering)
+	case blackfriday.CodeBlock:
+		out(w, codeTag)
+		escapeSpecialChars(w, node.Literal)
+		out(w, codeCloseTag)
+	case blackfriday.Table:
+		r.handleTable(w, node, entering)
+	case blackfriday.TableHead:
+	case blackfriday.TableBody:
+	case blackfriday.TableRow:
+		// no action as cell entries do all the nroff formatting
+		return blackfriday.GoToNext
+	case blackfriday.TableCell:
+		r.handleTableCell(w, node, entering)
+	case blackfriday.HTMLSpan:
+		// ignore other HTML tags
+	case blackfriday.HTMLBlock:
+		if bytes.HasPrefix(node.Literal, []byte("<!--")) {
+			break // ignore comments, no warning
+		}
+		fmt.Fprintln(os.Stderr, "WARNING: go-md2man does not handle node type "+node.Type.String())
+	default:
+		fmt.Fprintln(os.Stderr, "WARNING: go-md2man does not handle node type "+node.Type.String())
+	}
+	return walkAction
+}
+
+func (r *roffRenderer) handleHeading(w io.Writer, node *blackfriday.Node, entering bool) {
+	if entering {
+		switch node.Level {
+		case 1:
+			if !r.firstHeader {
+				out(w, titleHeader)
+				r.firstHeader = true
+				break
+			}
+			out(w, topLevelHeader)
+		case 2:
+			out(w, secondLevelHdr)
+		default:
+			out(w, otherHeader)
+		}
+	}
+}
+
+func (r *roffRenderer) handleList(w io.Writer, node *blackfriday.Node, entering bool) {
+	openTag := listTag
+	closeTag := listCloseTag
+	if node.ListFlags&blackfriday.ListTypeDefinition != 0 {
+		// tags for definition lists handled within Item node
+		openTag = ""
+		closeTag = ""
+	}
+	if entering {
+		r.listDepth++
+		if node.ListFlags&blackfriday.ListTypeOrdered != 0 {
+			r.listCounters = append(r.listCounters, 1)
+		}
+		out(w, openTag)
+	} else {
+		if node.ListFlags&blackfriday.ListTypeOrdered != 0 {
+			r.listCounters = r.listCounters[:len(r.listCounters)-1]
+		}
+		out(w, closeTag)
+		r.listDepth--
+	}
+}
+
+func (r *roffRenderer) handleItem(w io.Writer, node *blackfriday.Node, entering bool) {
+	if entering {
+		if node.ListFlags&blackfriday.ListTypeOrdered != 0 {
+			out(w, fmt.Sprintf(".IP \"%3d.\" 5\n", r.listCounters[len(r.listCounters)-1]))
+			r.listCounters[len(r.listCounters)-1]++
+		} else if node.ListFlags&blackfriday.ListTypeTerm != 0 {
+			// DT (definition term): line just before DD (see below).
+			out(w, dtTag)
+			r.firstDD = true
+		} else if node.ListFlags&blackfriday.ListTypeDefinition != 0 {
+			// DD (definition description): line that starts with ": ".
+			//
+			// We have to distinguish between the first DD and the
+			// subsequent ones, as there should be no vertical
+			// whitespace between the DT and the first DD.
+			if r.firstDD {
+				r.firstDD = false
+			} else {
+				out(w, dd2Tag)
+			}
+		} else {
+			out(w, ".IP \\(bu 2\n")
+		}
+	} else {
+		out(w, "\n")
+	}
+}
+
+func (r *roffRenderer) handleTable(w io.Writer, node *blackfriday.Node, entering bool) {
+	if entering {
+		out(w, tableStart)
+		// call walker to count cells (and rows?) so format section can be produced
+		columns := countColumns(node)
+		out(w, strings.Repeat("l ", columns)+"\n")
+		out(w, strings.Repeat("l ", columns)+".\n")
+	} else {
+		out(w, tableEnd)
+	}
+}
+
+func (r *roffRenderer) handleTableCell(w io.Writer, node *blackfriday.Node, entering bool) {
+	if entering {
+		var start string
+		if node.Prev != nil && node.Prev.Type == blackfriday.TableCell {
+			start = "\t"
+		}
+		if node.IsHeader {
+			start += strongTag
+		} else if nodeLiteralSize(node) > 30 {
+			start += tableCellStart
+		}
+		out(w, start)
+	} else {
+		var end string
+		if node.IsHeader {
+			end = strongCloseTag
+		} else if nodeLiteralSize(node) > 30 {
+			end = tableCellEnd
+		}
+		if node.Next == nil && end != tableCellEnd {
+			// Last cell: need to carriage return if we are at the end of the
+			// header row and content isn't wrapped in a "tablecell"
+			end += crTag
+		}
+		out(w, end)
+	}
+}
+
+func nodeLiteralSize(node *blackfriday.Node) int {
+	total := 0
+	for n := node.FirstChild; n != nil; n = n.FirstChild {
+		total += len(n.Literal)
+	}
+	return total
+}
+
+// because roff format requires knowing the column count before outputting any table
+// data we need to walk a table tree and count the columns
+func countColumns(node *blackfriday.Node) int {
+	var columns int
+
+	node.Walk(func(node *blackfriday.Node, entering bool) blackfriday.WalkStatus {
+		switch node.Type {
+		case blackfriday.TableRow:
+			if !entering {
+				return blackfriday.Terminate
+			}
+		case blackfriday.TableCell:
+			if entering {
+				columns++
+			}
+		default:
+		}
+		return blackfriday.GoToNext
+	})
+	return columns
+}
+
+func out(w io.Writer, output string) {
+	io.WriteString(w, output) // nolint: errcheck
+}
+
+func escapeSpecialChars(w io.Writer, text []byte) {
+	for i := 0; i < len(text); i++ {
+		// escape initial apostrophe or period
+		if len(text) >= 1 && (text[0] == '\'' || text[0] == '.') {
+			out(w, "\\&")
+		}
+
+		// directly copy normal characters
+		org := i
+
+		for i < len(text) && text[i] != '\\' {
+			i++
+		}
+		if i > org {
+			w.Write(text[org:i]) // nolint: errcheck
+		}
+
+		// escape a character
+		if i >= len(text) {
+			break
+		}
+
+		w.Write([]byte{'\\', text[i]}) // nolint: errcheck
+	}
+}
diff --git a/vendor/github.com/docker/cli-docs-tool/.dockerignore b/vendor/github.com/docker/cli-docs-tool/.dockerignore
new file mode 100644
index 000000000000..c8c323c89663
--- /dev/null
+++ b/vendor/github.com/docker/cli-docs-tool/.dockerignore
@@ -0,0 +1,2 @@
+/coverage.txt
+/example/docs
diff --git a/vendor/github.com/docker/cli-docs-tool/.gitignore b/vendor/github.com/docker/cli-docs-tool/.gitignore
new file mode 100644
index 000000000000..c8c323c89663
--- /dev/null
+++ b/vendor/github.com/docker/cli-docs-tool/.gitignore
@@ -0,0 +1,2 @@
+/coverage.txt
+/example/docs
diff --git a/vendor/github.com/docker/cli-docs-tool/.golangci.yml b/vendor/github.com/docker/cli-docs-tool/.golangci.yml
new file mode 100644
index 000000000000..6c6557176b28
--- /dev/null
+++ b/vendor/github.com/docker/cli-docs-tool/.golangci.yml
@@ -0,0 +1,37 @@
+run:
+  timeout: 10m
+
+linters:
+  enable:
+    - deadcode
+    - depguard
+    - gofmt
+    - goimports
+    - revive
+    - govet
+    - importas
+    - ineffassign
+    - misspell
+    - typecheck
+    - varcheck
+    - errname
+    - makezero
+    - whitespace
+  disable-all: true
+
+linters-settings:
+  depguard:
+    list-type: blacklist
+    include-go-root: true
+    packages:
+      # The io/ioutil package has been deprecated.
+      # https://go.dev/doc/go1.16#ioutil
+      - io/ioutil
+  importas:
+    no-unaliased: true
+
+issues:
+  exclude-rules:
+    - linters:
+        - revive
+      text: "stutters"
diff --git a/vendor/github.com/docker/cli-docs-tool/Dockerfile b/vendor/github.com/docker/cli-docs-tool/Dockerfile
new file mode 100644
index 000000000000..f0e2739faa7c
--- /dev/null
+++ b/vendor/github.com/docker/cli-docs-tool/Dockerfile
@@ -0,0 +1,86 @@
+# syntax=docker/dockerfile:1
+
+# Copyright 2021 cli-docs-tool authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+ARG GO_VERSION="1.18"
+ARG GOLANGCI_LINT_VERSION="v1.45"
+ARG ADDLICENSE_VERSION="v1.0.0"
+
+ARG LICENSE_ARGS="-c cli-docs-tool -l apache"
+ARG LICENSE_FILES=".*\(Dockerfile\|\.go\|\.hcl\|\.sh\)"
+
+FROM golangci/golangci-lint:${GOLANGCI_LINT_VERSION}-alpine AS golangci-lint
+FROM ghcr.io/google/addlicense:${ADDLICENSE_VERSION} AS addlicense
+
+FROM golang:${GO_VERSION}-alpine AS base
+RUN apk add --no-cache cpio findutils git linux-headers
+ENV CGO_ENABLED=0
+WORKDIR /src
+
+FROM base AS vendored
+RUN --mount=type=bind,target=.,rw \
+  --mount=type=cache,target=/go/pkg/mod \
+  go mod tidy && go mod download && \
+  mkdir /out && cp go.mod go.sum /out
+
+FROM scratch AS vendor-update
+COPY --from=vendored /out /
+
+FROM vendored AS vendor-validate
+RUN --mount=type=bind,target=.,rw <<EOT
+set -e
+git add -A
+cp -rf /out/* .
+diff=$(git status --porcelain -- go.mod go.sum)
+if [ -n "$diff" ]; then
+  echo >&2 'ERROR: Vendor result differs. Please vendor your package with "docker buildx bake vendor"'
+  echo "$diff"
+  exit 1
+fi
+EOT
+
+FROM base AS lint
+RUN --mount=type=bind,target=. \
+  --mount=type=cache,target=/root/.cache \
+  --mount=from=golangci-lint,source=/usr/bin/golangci-lint,target=/usr/bin/golangci-lint \
+  golangci-lint run ./...
+
+FROM base AS license-set
+ARG LICENSE_ARGS
+ARG LICENSE_FILES
+RUN --mount=type=bind,target=.,rw \
+  --mount=from=addlicense,source=/app/addlicense,target=/usr/bin/addlicense \
+  find . -regex "${LICENSE_FILES}" | xargs addlicense ${LICENSE_ARGS} \
+  && mkdir /out \
+  && find . -regex "${LICENSE_FILES}" | cpio -pdm /out
+
+FROM scratch AS license-update
+COPY --from=set /out /
+
+FROM base AS license-validate
+ARG LICENSE_ARGS
+ARG LICENSE_FILES
+RUN --mount=type=bind,target=. \
+  --mount=from=addlicense,source=/app/addlicense,target=/usr/bin/addlicense \
+  find . -regex "${LICENSE_FILES}" | xargs addlicense -check ${LICENSE_ARGS}
+
+FROM vendored AS test
+RUN --mount=type=bind,target=. \
+  --mount=type=cache,target=/root/.cache \
+  --mount=type=cache,target=/go/pkg/mod \
+  go test -v -coverprofile=/tmp/coverage.txt -covermode=atomic ./...
+
+FROM scratch AS test-coverage
+COPY --from=test /tmp/coverage.txt /coverage.txt
diff --git a/vendor/github.com/docker/cli-docs-tool/LICENSE b/vendor/github.com/docker/cli-docs-tool/LICENSE
new file mode 100644
index 000000000000..d64569567334
--- /dev/null
+++ b/vendor/github.com/docker/cli-docs-tool/LICENSE
@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/vendor/github.com/docker/cli-docs-tool/README.md b/vendor/github.com/docker/cli-docs-tool/README.md
new file mode 100644
index 000000000000..4d5ee6474f8f
--- /dev/null
+++ b/vendor/github.com/docker/cli-docs-tool/README.md
@@ -0,0 +1,67 @@
+[![PkgGoDev](https://img.shields.io/badge/go.dev-docs-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/docker/cli-docs-tool)
+[![Test Status](https://img.shields.io/github/actions/workflow/status/docker/cli-docs-tool/test.yml?branch=main&label=test&logo=github&style=flat-square)](https://github.com/docker/cli-docs-tool/actions?query=workflow%3Atest)
+[![Go Report Card](https://goreportcard.com/badge/github.com/docker/cli-docs-tool)](https://goreportcard.com/report/github.com/docker/cli-docs-tool)
+
+## About
+
+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
+
+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/cli-docs-tool
+```
+
+Your `go.mod` should look like this:
+
+```text
+module github.com/docker/buildx/docs
+
+go 1.16
+
+require (
+	github.com/docker/cli-docs-tool v0.0.0
+)
+```
+
+Next, create a file named `main.go` inside that directory containing the
+following Go code from [`example/main.go`](example/main.go).
+
+Running this example should produce the following output:
+
+```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
+
+Want to contribute? Awesome! You can find information about contributing to
+this project in the [CONTRIBUTING.md](/.github/CONTRIBUTING.md)
diff --git a/vendor/github.com/docker/cli-docs-tool/annotation/annotation.go b/vendor/github.com/docker/cli-docs-tool/annotation/annotation.go
new file mode 100644
index 000000000000..021846af6e07
--- /dev/null
+++ b/vendor/github.com/docker/cli-docs-tool/annotation/annotation.go
@@ -0,0 +1,25 @@
+// Copyright 2021 cli-docs-tool authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package annotation
+
+const (
+	// ExternalURL specifies an external link annotation
+	ExternalURL = "docs.external.url"
+	// CodeDelimiter specifies the char that will be converted as code backtick.
+	// Can be used on cmd for inheritance or a specific flag.
+	CodeDelimiter = "docs.code-delimiter"
+	// DefaultValue specifies the default value for a flag.
+	DefaultValue = "docs.default-value"
+)
diff --git a/vendor/github.com/docker/cli-docs-tool/clidocstool.go b/vendor/github.com/docker/cli-docs-tool/clidocstool.go
new file mode 100644
index 000000000000..d4aeaba3f126
--- /dev/null
+++ b/vendor/github.com/docker/cli-docs-tool/clidocstool.go
@@ -0,0 +1,123 @@
+// Copyright 2017 cli-docs-tool authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package clidocstool
+
+import (
+	"errors"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// Options defines options for cli-docs-tool
+type Options struct {
+	Root      *cobra.Command
+	SourceDir string
+	TargetDir string
+	Plugin    bool
+}
+
+// Client represents an active cli-docs-tool object
+type Client struct {
+	root   *cobra.Command
+	source string
+	target string
+	plugin bool
+}
+
+// New initializes a new cli-docs-tool client
+func New(opts Options) (*Client, error) {
+	if opts.Root == nil {
+		return nil, errors.New("root cmd required")
+	}
+	if len(opts.SourceDir) == 0 {
+		return nil, errors.New("source dir required")
+	}
+	c := &Client{
+		root:   opts.Root,
+		source: opts.SourceDir,
+		plugin: opts.Plugin,
+	}
+	if len(opts.TargetDir) == 0 {
+		c.target = c.source
+	} else {
+		c.target = opts.TargetDir
+	}
+	if err := os.MkdirAll(c.target, 0755); err != nil {
+		return nil, err
+	}
+	return c, nil
+}
+
+// GenAllTree creates all structured ref files for this command and
+// all descendants in the directory given.
+func (c *Client) GenAllTree() error {
+	var err error
+	if err = c.GenMarkdownTree(c.root); err != nil {
+		return err
+	}
+	if err = c.GenYamlTree(c.root); err != nil {
+		return err
+	}
+	return nil
+}
+
+func fileExists(f string) bool {
+	info, err := os.Stat(f)
+	if os.IsNotExist(err) {
+		return false
+	}
+	return !info.IsDir()
+}
+
+func copyFile(src string, dst string) error {
+	sf, err := os.Open(src)
+	if err != nil {
+		return err
+	}
+	defer sf.Close()
+	df, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY, 0o600)
+	if err != nil {
+		return err
+	}
+	defer df.Close()
+	_, err = io.Copy(df, sf)
+	return err
+}
+
+func getAliases(cmd *cobra.Command) []string {
+	if a := cmd.Annotations["aliases"]; a != "" {
+		aliases := strings.Split(a, ",")
+		for i := 0; i < len(aliases); i++ {
+			aliases[i] = strings.TrimSpace(aliases[i])
+		}
+		return aliases
+	}
+	if len(cmd.Aliases) == 0 {
+		return cmd.Aliases
+	}
+
+	var parentPath string
+	if cmd.HasParent() {
+		parentPath = cmd.Parent().CommandPath() + " "
+	}
+	aliases := []string{cmd.CommandPath()}
+	for _, a := range cmd.Aliases {
+		aliases = append(aliases, parentPath+a)
+	}
+	return aliases
+}
diff --git a/vendor/github.com/docker/cli-docs-tool/clidocstool_md.go b/vendor/github.com/docker/cli-docs-tool/clidocstool_md.go
new file mode 100644
index 000000000000..1dee58c06ca1
--- /dev/null
+++ b/vendor/github.com/docker/cli-docs-tool/clidocstool_md.go
@@ -0,0 +1,280 @@
+// Copyright 2021 cli-docs-tool authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package clidocstool
+
+import (
+	"bytes"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"text/tabwriter"
+	"text/template"
+
+	"github.com/docker/cli-docs-tool/annotation"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+var (
+	nlRegexp  = regexp.MustCompile(`\r?\n`)
+	adjustSep = regexp.MustCompile(`\|:---(\s+)`)
+)
+
+// GenMarkdownTree will generate a markdown page for this command and all
+// descendants in the directory given.
+func (c *Client) GenMarkdownTree(cmd *cobra.Command) error {
+	for _, sc := range cmd.Commands() {
+		if err := c.GenMarkdownTree(sc); err != nil {
+			return err
+		}
+	}
+
+	// always disable the addition of [flags] to the usage
+	cmd.DisableFlagsInUseLine = true
+
+	// Skip the root command altogether, to prevent generating a useless
+	// md file for plugins.
+	if c.plugin && !cmd.HasParent() {
+		return nil
+	}
+
+	// Skip hidden command
+	if cmd.Hidden {
+		log.Printf("INFO: Skipping Markdown for %q (hidden command)", cmd.CommandPath())
+		return nil
+	}
+
+	log.Printf("INFO: Generating Markdown for %q", cmd.CommandPath())
+	mdFile := mdFilename(cmd)
+	sourcePath := filepath.Join(c.source, mdFile)
+	targetPath := filepath.Join(c.target, mdFile)
+
+	// check recursively to handle inherited annotations
+	for curr := cmd; curr != nil; curr = curr.Parent() {
+		if _, ok := cmd.Annotations[annotation.CodeDelimiter]; !ok {
+			if cd, cok := curr.Annotations[annotation.CodeDelimiter]; cok {
+				if cmd.Annotations == nil {
+					cmd.Annotations = map[string]string{}
+				}
+				cmd.Annotations[annotation.CodeDelimiter] = cd
+			}
+		}
+	}
+
+	if !fileExists(sourcePath) {
+		var icBuf bytes.Buffer
+		icTpl, err := template.New("ic").Option("missingkey=error").Parse(`# {{ .Command }}
+
+<!---MARKER_GEN_START-->
+<!---MARKER_GEN_END-->
+
+`)
+		if err != nil {
+			return err
+		}
+		if err = icTpl.Execute(&icBuf, struct {
+			Command string
+		}{
+			Command: cmd.CommandPath(),
+		}); err != nil {
+			return err
+		}
+		if err = os.WriteFile(targetPath, icBuf.Bytes(), 0644); err != nil {
+			return err
+		}
+	} else if err := copyFile(sourcePath, targetPath); err != nil {
+		return err
+	}
+
+	content, err := os.ReadFile(targetPath)
+	if err != nil {
+		return err
+	}
+
+	cs := string(content)
+
+	start := strings.Index(cs, "<!---MARKER_GEN_START-->")
+	end := strings.Index(cs, "<!---MARKER_GEN_END-->")
+
+	if start == -1 {
+		return fmt.Errorf("no start marker in %s", mdFile)
+	}
+	if end == -1 {
+		return fmt.Errorf("no end marker in %s", mdFile)
+	}
+
+	out, err := mdCmdOutput(cmd, cs)
+	if err != nil {
+		return err
+	}
+	cont := cs[:start] + "<!---MARKER_GEN_START-->" + "\n" + out + "\n" + cs[end:]
+
+	fi, err := os.Stat(targetPath)
+	if err != nil {
+		return err
+	}
+	if err = os.WriteFile(targetPath, []byte(cont), fi.Mode()); err != nil {
+		return fmt.Errorf("failed to write %s: %w", targetPath, err)
+	}
+
+	return nil
+}
+
+func mdFilename(cmd *cobra.Command) string {
+	name := cmd.CommandPath()
+	if i := strings.Index(name, " "); i >= 0 {
+		name = name[i+1:]
+	}
+	return strings.ReplaceAll(name, " ", "_") + ".md"
+}
+
+func mdMakeLink(txt, link string, f *pflag.Flag, isAnchor bool) string {
+	link = "#" + link
+	annotations, ok := f.Annotations[annotation.ExternalURL]
+	if ok && len(annotations) > 0 {
+		link = annotations[0]
+	} else {
+		if !isAnchor {
+			return txt
+		}
+	}
+
+	return "[" + txt + "](" + link + ")"
+}
+
+type mdTable struct {
+	out       *strings.Builder
+	tabWriter *tabwriter.Writer
+}
+
+func newMdTable(headers ...string) *mdTable {
+	w := &strings.Builder{}
+	t := &mdTable{
+		out: w,
+		// Using tabwriter.Debug, which uses "|" as separator instead of tabs,
+		// which is what we want. It's a bit of a hack, but does the job :)
+		tabWriter: tabwriter.NewWriter(w, 5, 5, 1, ' ', tabwriter.Debug),
+	}
+	t.addHeader(headers...)
+	return t
+}
+
+func (t *mdTable) addHeader(cols ...string) {
+	t.AddRow(cols...)
+	_, _ = t.tabWriter.Write([]byte("|" + strings.Repeat(":---\t", len(cols)) + "\n"))
+}
+
+func (t *mdTable) AddRow(cols ...string) {
+	for i := range cols {
+		cols[i] = mdEscapePipe(cols[i])
+	}
+	_, _ = t.tabWriter.Write([]byte("| " + strings.Join(cols, "\t ") + "\t\n"))
+}
+
+func (t *mdTable) String() string {
+	_ = t.tabWriter.Flush()
+	return adjustSep.ReplaceAllStringFunc(t.out.String()+"\n", func(in string) string {
+		return strings.ReplaceAll(in, " ", "-")
+	})
+}
+
+func mdCmdOutput(cmd *cobra.Command, old string) (string, error) {
+	b := &strings.Builder{}
+
+	desc := cmd.Short
+	if cmd.Long != "" {
+		desc = cmd.Long
+	}
+	if desc != "" {
+		b.WriteString(desc + "\n\n")
+	}
+
+	if aliases := getAliases(cmd); len(aliases) != 0 {
+		b.WriteString("### Aliases\n\n")
+		b.WriteString("`" + strings.Join(aliases, "`, `") + "`")
+		b.WriteString("\n\n")
+	}
+
+	if len(cmd.Commands()) != 0 {
+		b.WriteString("### Subcommands\n\n")
+		table := newMdTable("Name", "Description")
+		for _, c := range cmd.Commands() {
+			if c.Hidden {
+				continue
+			}
+			table.AddRow(fmt.Sprintf("[`%s`](%s)", c.Name(), mdFilename(c)), c.Short)
+		}
+		b.WriteString(table.String() + "\n")
+	}
+
+	// add inherited flags before checking for flags availability
+	cmd.Flags().AddFlagSet(cmd.InheritedFlags())
+
+	if cmd.Flags().HasAvailableFlags() {
+		b.WriteString("### Options\n\n")
+		table := newMdTable("Name", "Type", "Default", "Description")
+		cmd.Flags().VisitAll(func(f *pflag.Flag) {
+			if f.Hidden {
+				return
+			}
+			isLink := strings.Contains(old, "<a name=\""+f.Name+"\"></a>")
+			var name string
+			if f.Shorthand != "" {
+				name = mdMakeLink("`-"+f.Shorthand+"`", f.Name, f, isLink)
+				name += ", "
+			}
+			name += mdMakeLink("`--"+f.Name+"`", f.Name, f, isLink)
+
+			var ftype string
+			if f.Value.Type() != "bool" {
+				ftype = "`" + f.Value.Type() + "`"
+			}
+
+			var defval string
+			if v, ok := f.Annotations[annotation.DefaultValue]; ok && len(v) > 0 {
+				defval = v[0]
+				if cd, ok := f.Annotations[annotation.CodeDelimiter]; ok {
+					defval = strings.ReplaceAll(defval, cd[0], "`")
+				} else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok {
+					defval = strings.ReplaceAll(defval, cd, "`")
+				}
+			} else if f.DefValue != "" && (f.Value.Type() != "bool" && f.DefValue != "true") && f.DefValue != "[]" {
+				defval = "`" + f.DefValue + "`"
+			}
+
+			usage := f.Usage
+			if cd, ok := f.Annotations[annotation.CodeDelimiter]; ok {
+				usage = strings.ReplaceAll(usage, cd[0], "`")
+			} else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok {
+				usage = strings.ReplaceAll(usage, cd, "`")
+			}
+			table.AddRow(name, ftype, defval, mdReplaceNewline(usage))
+		})
+		b.WriteString(table.String())
+	}
+
+	return b.String(), nil
+}
+
+func mdEscapePipe(s string) string {
+	return strings.ReplaceAll(s, `|`, `\|`)
+}
+
+func mdReplaceNewline(s string) string {
+	return nlRegexp.ReplaceAllString(s, "<br>")
+}
diff --git a/vendor/github.com/docker/cli-docs-tool/clidocstool_yaml.go b/vendor/github.com/docker/cli-docs-tool/clidocstool_yaml.go
new file mode 100644
index 000000000000..523524297af4
--- /dev/null
+++ b/vendor/github.com/docker/cli-docs-tool/clidocstool_yaml.go
@@ -0,0 +1,435 @@
+// Copyright 2017 cli-docs-tool authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package clidocstool
+
+import (
+	"fmt"
+	"io"
+	"log"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/docker/cli-docs-tool/annotation"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+	"gopkg.in/yaml.v3"
+)
+
+type cmdOption struct {
+	Option          string
+	Shorthand       string `yaml:",omitempty"`
+	ValueType       string `yaml:"value_type,omitempty"`
+	DefaultValue    string `yaml:"default_value,omitempty"`
+	Description     string `yaml:",omitempty"`
+	DetailsURL      string `yaml:"details_url,omitempty"` // DetailsURL contains an anchor-id or link for more information on this flag
+	Deprecated      bool
+	Hidden          bool
+	MinAPIVersion   string `yaml:"min_api_version,omitempty"`
+	Experimental    bool
+	ExperimentalCLI bool
+	Kubernetes      bool
+	Swarm           bool
+	OSType          string `yaml:"os_type,omitempty"`
+}
+
+type cmdDoc struct {
+	Name             string      `yaml:"command"`
+	SeeAlso          []string    `yaml:"parent,omitempty"`
+	Version          string      `yaml:"engine_version,omitempty"`
+	Aliases          string      `yaml:",omitempty"`
+	Short            string      `yaml:",omitempty"`
+	Long             string      `yaml:",omitempty"`
+	Usage            string      `yaml:",omitempty"`
+	Pname            string      `yaml:",omitempty"`
+	Plink            string      `yaml:",omitempty"`
+	Cname            []string    `yaml:",omitempty"`
+	Clink            []string    `yaml:",omitempty"`
+	Options          []cmdOption `yaml:",omitempty"`
+	InheritedOptions []cmdOption `yaml:"inherited_options,omitempty"`
+	Example          string      `yaml:"examples,omitempty"`
+	Deprecated       bool
+	Hidden           bool
+	MinAPIVersion    string `yaml:"min_api_version,omitempty"`
+	Experimental     bool
+	ExperimentalCLI  bool
+	Kubernetes       bool
+	Swarm            bool
+	OSType           string `yaml:"os_type,omitempty"`
+}
+
+// GenYamlTree creates yaml structured ref files for this command and all descendants
+// in the directory given. This function may not work
+// correctly if your command names have `-` in them. If you have `cmd` with two
+// subcmds, `sub` and `sub-third`, and `sub` has a subcommand called `third`
+// it is undefined which help output will be in the file `cmd-sub-third.1`.
+func (c *Client) GenYamlTree(cmd *cobra.Command) error {
+	emptyStr := func(s string) string { return "" }
+	if err := c.loadLongDescription(cmd); err != nil {
+		return err
+	}
+	return c.genYamlTreeCustom(cmd, emptyStr)
+}
+
+// genYamlTreeCustom creates yaml structured ref files.
+func (c *Client) genYamlTreeCustom(cmd *cobra.Command, filePrepender func(string) string) error {
+	for _, sc := range cmd.Commands() {
+		if !sc.Runnable() && !sc.HasAvailableSubCommands() {
+			// skip non-runnable commands without subcommands
+			// but *do* generate YAML for hidden and deprecated commands
+			// the YAML will have those included as metadata, so that the
+			// documentation repository can decide whether or not to present them
+			continue
+		}
+		if err := c.genYamlTreeCustom(sc, filePrepender); err != nil {
+			return err
+		}
+	}
+
+	// always disable the addition of [flags] to the usage
+	cmd.DisableFlagsInUseLine = true
+
+	// The "root" command used in the generator is just a "stub", and only has a
+	// list of subcommands, but not (e.g.) global options/flags. We should fix
+	// that, so that the YAML file for the docker "root" command contains the
+	// global flags.
+
+	// Skip the root command altogether, to prevent generating a useless
+	// YAML file for plugins.
+	if c.plugin && !cmd.HasParent() {
+		return nil
+	}
+
+	log.Printf("INFO: Generating YAML for %q", cmd.CommandPath())
+	basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".yaml"
+	target := filepath.Join(c.target, basename)
+	f, err := os.Create(target)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	if _, err := io.WriteString(f, filePrepender(target)); err != nil {
+		return err
+	}
+	return c.genYamlCustom(cmd, f)
+}
+
+// genYamlCustom creates custom yaml output.
+// nolint: gocyclo
+func (c *Client) genYamlCustom(cmd *cobra.Command, w io.Writer) error {
+	const (
+		// shortMaxWidth is the maximum width for the "Short" description before
+		// we force YAML to use multi-line syntax. The goal is to make the total
+		// width fit within 80 characters. This value is based on 80 characters
+		// minus the with of the field, colon, and whitespace ('short: ').
+		shortMaxWidth = 73
+
+		// longMaxWidth is the maximum width for the "Short" description before
+		// we force YAML to use multi-line syntax. The goal is to make the total
+		// width fit within 80 characters. This value is based on 80 characters
+		// minus the with of the field, colon, and whitespace ('long: ').
+		longMaxWidth = 74
+	)
+
+	// necessary to add inherited flags otherwise some
+	// fields are not properly declared like usage
+	cmd.Flags().AddFlagSet(cmd.InheritedFlags())
+
+	cliDoc := cmdDoc{
+		Name:       cmd.CommandPath(),
+		Aliases:    strings.Join(getAliases(cmd), ", "),
+		Short:      forceMultiLine(cmd.Short, shortMaxWidth),
+		Long:       forceMultiLine(cmd.Long, longMaxWidth),
+		Example:    cmd.Example,
+		Deprecated: len(cmd.Deprecated) > 0,
+		Hidden:     cmd.Hidden,
+	}
+
+	if len(cliDoc.Long) == 0 {
+		cliDoc.Long = cliDoc.Short
+	}
+
+	if cmd.Runnable() {
+		cliDoc.Usage = cmd.UseLine()
+	}
+
+	// check recursively to handle inherited annotations
+	for curr := cmd; curr != nil; curr = curr.Parent() {
+		if v, ok := curr.Annotations["version"]; ok && cliDoc.MinAPIVersion == "" {
+			cliDoc.MinAPIVersion = v
+		}
+		if _, ok := curr.Annotations["experimental"]; ok && !cliDoc.Experimental {
+			cliDoc.Experimental = true
+		}
+		if _, ok := curr.Annotations["experimentalCLI"]; ok && !cliDoc.ExperimentalCLI {
+			cliDoc.ExperimentalCLI = true
+		}
+		if _, ok := curr.Annotations["kubernetes"]; ok && !cliDoc.Kubernetes {
+			cliDoc.Kubernetes = true
+		}
+		if _, ok := curr.Annotations["swarm"]; ok && !cliDoc.Swarm {
+			cliDoc.Swarm = true
+		}
+		if o, ok := curr.Annotations["ostype"]; ok && cliDoc.OSType == "" {
+			cliDoc.OSType = o
+		}
+		if _, ok := cmd.Annotations[annotation.CodeDelimiter]; !ok {
+			if cd, cok := curr.Annotations[annotation.CodeDelimiter]; cok {
+				if cmd.Annotations == nil {
+					cmd.Annotations = map[string]string{}
+				}
+				cmd.Annotations[annotation.CodeDelimiter] = cd
+			}
+		}
+	}
+
+	anchors := make(map[string]struct{})
+	if a, ok := cmd.Annotations["anchors"]; ok && a != "" {
+		for _, anchor := range strings.Split(a, ",") {
+			anchors[anchor] = struct{}{}
+		}
+	}
+
+	flags := cmd.NonInheritedFlags()
+	if flags.HasFlags() {
+		cliDoc.Options = genFlagResult(cmd, flags, anchors)
+	}
+	flags = cmd.InheritedFlags()
+	if flags.HasFlags() {
+		cliDoc.InheritedOptions = genFlagResult(cmd, flags, anchors)
+	}
+
+	if hasSeeAlso(cmd) {
+		if cmd.HasParent() {
+			parent := cmd.Parent()
+			cliDoc.Pname = parent.CommandPath()
+			cliDoc.Plink = strings.Replace(cliDoc.Pname, " ", "_", -1) + ".yaml"
+			cmd.VisitParents(func(c *cobra.Command) {
+				if c.DisableAutoGenTag {
+					cmd.DisableAutoGenTag = c.DisableAutoGenTag
+				}
+			})
+		}
+
+		children := cmd.Commands()
+		sort.Sort(byName(children))
+
+		for _, child := range children {
+			if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() {
+				continue
+			}
+			cliDoc.Cname = append(cliDoc.Cname, cliDoc.Name+" "+child.Name())
+			cliDoc.Clink = append(cliDoc.Clink, strings.Replace(cliDoc.Name+"_"+child.Name(), " ", "_", -1)+".yaml")
+		}
+	}
+
+	final, err := yaml.Marshal(&cliDoc)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	if _, err := fmt.Fprintln(w, string(final)); err != nil {
+		return err
+	}
+	return nil
+}
+
+func genFlagResult(cmd *cobra.Command, flags *pflag.FlagSet, anchors map[string]struct{}) []cmdOption {
+	var (
+		result []cmdOption
+		opt    cmdOption
+	)
+
+	const (
+		// shortMaxWidth is the maximum width for the "Short" description before
+		// we force YAML to use multi-line syntax. The goal is to make the total
+		// width fit within 80 characters. This value is based on 80 characters
+		// minus the with of the field, colon, and whitespace ('  default_value: ').
+		defaultValueMaxWidth = 64
+
+		// longMaxWidth is the maximum width for the "Short" description before
+		// we force YAML to use multi-line syntax. The goal is to make the total
+		// width fit within 80 characters. This value is based on 80 characters
+		// minus the with of the field, colon, and whitespace ('  description: ').
+		descriptionMaxWidth = 66
+	)
+
+	flags.VisitAll(func(flag *pflag.Flag) {
+		opt = cmdOption{
+			Option:     flag.Name,
+			ValueType:  flag.Value.Type(),
+			Deprecated: len(flag.Deprecated) > 0,
+			Hidden:     flag.Hidden,
+		}
+
+		var defval string
+		if v, ok := flag.Annotations[annotation.DefaultValue]; ok && len(v) > 0 {
+			defval = v[0]
+			if cd, ok := flag.Annotations[annotation.CodeDelimiter]; ok {
+				defval = strings.ReplaceAll(defval, cd[0], "`")
+			} else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok {
+				defval = strings.ReplaceAll(defval, cd, "`")
+			}
+		} else {
+			defval = flag.DefValue
+		}
+		opt.DefaultValue = forceMultiLine(defval, defaultValueMaxWidth)
+
+		usage := flag.Usage
+		if cd, ok := flag.Annotations[annotation.CodeDelimiter]; ok {
+			usage = strings.ReplaceAll(usage, cd[0], "`")
+		} else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok {
+			usage = strings.ReplaceAll(usage, cd, "`")
+		}
+		opt.Description = forceMultiLine(usage, descriptionMaxWidth)
+
+		if v, ok := flag.Annotations[annotation.ExternalURL]; ok && len(v) > 0 {
+			opt.DetailsURL = strings.TrimPrefix(v[0], "https://docs.docker.com")
+		} else if _, ok = anchors[flag.Name]; ok {
+			opt.DetailsURL = "#" + flag.Name
+		}
+
+		// Todo, when we mark a shorthand is deprecated, but specify an empty message.
+		// The flag.ShorthandDeprecated is empty as the shorthand is deprecated.
+		// Using len(flag.ShorthandDeprecated) > 0 can't handle this, others are ok.
+		if !(len(flag.ShorthandDeprecated) > 0) && len(flag.Shorthand) > 0 {
+			opt.Shorthand = flag.Shorthand
+		}
+		if _, ok := flag.Annotations["experimental"]; ok {
+			opt.Experimental = true
+		}
+		if _, ok := flag.Annotations["deprecated"]; ok {
+			opt.Deprecated = true
+		}
+		if v, ok := flag.Annotations["version"]; ok {
+			opt.MinAPIVersion = v[0]
+		}
+		if _, ok := flag.Annotations["experimentalCLI"]; ok {
+			opt.ExperimentalCLI = true
+		}
+		if _, ok := flag.Annotations["kubernetes"]; ok {
+			opt.Kubernetes = true
+		}
+		if _, ok := flag.Annotations["swarm"]; ok {
+			opt.Swarm = true
+		}
+
+		// Note that the annotation can have multiple ostypes set, however, multiple
+		// values are currently not used (and unlikely will).
+		//
+		// To simplify usage of the os_type property in the YAML, and for consistency
+		// with the same property for commands, we're only using the first ostype that's set.
+		if ostypes, ok := flag.Annotations["ostype"]; ok && len(opt.OSType) == 0 && len(ostypes) > 0 {
+			opt.OSType = ostypes[0]
+		}
+
+		result = append(result, opt)
+	})
+
+	return result
+}
+
+// forceMultiLine appends a newline (\n) to strings that are longer than max
+// to force the yaml lib to use block notation (https://yaml.org/spec/1.2/spec.html#Block)
+// instead of a single-line string with newlines and tabs encoded("string\nline1\nline2").
+//
+// This makes the generated YAML more readable, and easier to review changes.
+// max can be used to customize the width to keep the whole line < 80 chars.
+func forceMultiLine(s string, max int) string {
+	s = strings.TrimSpace(s)
+	if len(s) > max && !strings.Contains(s, "\n") {
+		s = s + "\n"
+	}
+	return s
+}
+
+// Small duplication for cobra utils
+func hasSeeAlso(cmd *cobra.Command) bool {
+	if cmd.HasParent() {
+		return true
+	}
+	for _, c := range cmd.Commands() {
+		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
+			continue
+		}
+		return true
+	}
+	return false
+}
+
+// loadLongDescription gets long descriptions and examples from markdown.
+func (c *Client) loadLongDescription(parentCmd *cobra.Command) error {
+	for _, cmd := range parentCmd.Commands() {
+		if cmd.HasSubCommands() {
+			if err := c.loadLongDescription(cmd); err != nil {
+				return err
+			}
+		}
+		name := cmd.CommandPath()
+		if i := strings.Index(name, " "); i >= 0 {
+			// remove root command / binary name
+			name = name[i+1:]
+		}
+		if name == "" {
+			continue
+		}
+		mdFile := strings.ReplaceAll(name, " ", "_") + ".md"
+		sourcePath := filepath.Join(c.source, mdFile)
+		content, err := os.ReadFile(sourcePath)
+		if os.IsNotExist(err) {
+			log.Printf("WARN: %s does not exist, skipping Markdown examples for YAML doc\n", mdFile)
+			continue
+		}
+		if err != nil {
+			return err
+		}
+		applyDescriptionAndExamples(cmd, string(content))
+	}
+	return nil
+}
+
+// applyDescriptionAndExamples fills in cmd.Long and cmd.Example with the
+// "Description" and "Examples" H2 sections in  mdString (if present).
+func applyDescriptionAndExamples(cmd *cobra.Command, mdString string) {
+	sections := getSections(mdString)
+	var (
+		anchors []string
+		md      string
+	)
+	if sections["description"] != "" {
+		md, anchors = cleanupMarkDown(sections["description"])
+		cmd.Long = md
+		anchors = append(anchors, md)
+	}
+	if sections["examples"] != "" {
+		md, anchors = cleanupMarkDown(sections["examples"])
+		cmd.Example = md
+		anchors = append(anchors, md)
+	}
+	if len(anchors) > 0 {
+		if cmd.Annotations == nil {
+			cmd.Annotations = make(map[string]string)
+		}
+		cmd.Annotations["anchors"] = strings.Join(anchors, ",")
+	}
+}
+
+type byName []*cobra.Command
+
+func (s byName) Len() int           { return len(s) }
+func (s byName) Swap(i, j int)      { s[i], s[j] = s[j], s[i] }
+func (s byName) Less(i, j int) bool { return s[i].Name() < s[j].Name() }
diff --git a/vendor/github.com/docker/cli-docs-tool/docker-bake.hcl b/vendor/github.com/docker/cli-docs-tool/docker-bake.hcl
new file mode 100644
index 000000000000..4a5f44f83018
--- /dev/null
+++ b/vendor/github.com/docker/cli-docs-tool/docker-bake.hcl
@@ -0,0 +1,51 @@
+// Copyright 2021 cli-docs-tool authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+group "default" {
+  targets = ["test"]
+}
+
+group "validate" {
+  targets = ["lint", "vendor-validate", "license-validate"]
+}
+
+target "lint" {
+  target = "lint"
+  output = ["type=cacheonly"]
+}
+
+target "vendor-validate" {
+  target = "vendor-validate"
+  output = ["type=cacheonly"]
+}
+
+target "vendor-update" {
+  target = "vendor-update"
+  output = ["."]
+}
+
+target "test" {
+  target = "test-coverage"
+  output = ["."]
+}
+
+target "license-validate" {
+  target = "license-validate"
+  output = ["type=cacheonly"]
+}
+
+target "license-update" {
+  target = "license-update"
+  output = ["."]
+}
diff --git a/vendor/github.com/docker/cli-docs-tool/markdown.go b/vendor/github.com/docker/cli-docs-tool/markdown.go
new file mode 100644
index 000000000000..32849236ed9c
--- /dev/null
+++ b/vendor/github.com/docker/cli-docs-tool/markdown.go
@@ -0,0 +1,87 @@
+// Copyright 2017 cli-docs-tool authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package clidocstool
+
+import (
+	"regexp"
+	"strings"
+	"unicode"
+)
+
+var (
+	// mdHeading matches MarkDown H1..h6 headings. Note that this regex may produce
+	// false positives for (e.g.) comments in code-blocks (# this is a comment),
+	// so should not be used as a generic regex for other purposes.
+	mdHeading = regexp.MustCompile(`^([#]{1,6})\s(.*)$`)
+	// htmlAnchor matches inline HTML anchors. This is intended to only match anchors
+	// for our use-case; DO NOT consider using this as a generic regex, or at least
+	// not before reading https://stackoverflow.com/a/1732454/1811501.
+	htmlAnchor = regexp.MustCompile(`<a\s+(?:name|id)="?([^"]+)"?\s*></a>\s*`)
+)
+
+// getSections returns all H2 sections by title (lowercase)
+func getSections(mdString string) map[string]string {
+	parsedContent := strings.Split("\n"+mdString, "\n## ")
+	sections := make(map[string]string, len(parsedContent))
+	for _, s := range parsedContent {
+		if strings.HasPrefix(s, "#") {
+			// not a H2 Section
+			continue
+		}
+		parts := strings.SplitN(s, "\n", 2)
+		if len(parts) == 2 {
+			sections[strings.ToLower(parts[0])] = parts[1]
+		}
+	}
+	return sections
+}
+
+// cleanupMarkDown cleans up the MarkDown passed in mdString for inclusion in
+// YAML. It removes trailing whitespace and substitutes tabs for four spaces
+// to prevent YAML switching to use "compact" form; ("line1  \nline\t2\n")
+// which, although equivalent, is hard to read.
+func cleanupMarkDown(mdString string) (md string, anchors []string) {
+	// remove leading/trailing whitespace, and replace tabs in the whole content
+	mdString = strings.TrimSpace(mdString)
+	mdString = strings.ReplaceAll(mdString, "\t", "    ")
+	mdString = strings.ReplaceAll(mdString, "https://docs.docker.com", "")
+
+	var id string
+	// replace trailing whitespace per line, and handle custom anchors
+	lines := strings.Split(mdString, "\n")
+	for i := 0; i < len(lines); i++ {
+		lines[i] = strings.TrimRightFunc(lines[i], unicode.IsSpace)
+		lines[i], id = convertHTMLAnchor(lines[i])
+		if id != "" {
+			anchors = append(anchors, id)
+		}
+	}
+	return strings.Join(lines, "\n"), anchors
+}
+
+// convertHTMLAnchor converts inline anchor-tags in headings (<a name=myanchor></a>)
+// to an extended-markdown property ({#myanchor}). Extended Markdown properties
+// are not supported in GitHub Flavored Markdown, but are supported by Jekyll,
+// and lead to cleaner HTML in our docs, and prevents duplicate anchors.
+// It returns the converted MarkDown heading and the custom ID (if present)
+func convertHTMLAnchor(mdLine string) (md string, customID string) {
+	if m := mdHeading.FindStringSubmatch(mdLine); len(m) > 0 {
+		if a := htmlAnchor.FindStringSubmatch(m[2]); len(a) > 0 {
+			customID = a[1]
+			mdLine = m[1] + " " + htmlAnchor.ReplaceAllString(m[2], "") + " {#" + customID + "}"
+		}
+	}
+	return mdLine, customID
+}
diff --git a/vendor/github.com/russross/blackfriday/v2/.gitignore b/vendor/github.com/russross/blackfriday/v2/.gitignore
new file mode 100644
index 000000000000..75623dcccbb7
--- /dev/null
+++ b/vendor/github.com/russross/blackfriday/v2/.gitignore
@@ -0,0 +1,8 @@
+*.out
+*.swp
+*.8
+*.6
+_obj
+_test*
+markdown
+tags
diff --git a/vendor/github.com/russross/blackfriday/v2/.travis.yml b/vendor/github.com/russross/blackfriday/v2/.travis.yml
new file mode 100644
index 000000000000..b0b525a5a8e1
--- /dev/null
+++ b/vendor/github.com/russross/blackfriday/v2/.travis.yml
@@ -0,0 +1,17 @@
+sudo: false
+language: go
+go:
+  - "1.10.x"
+  - "1.11.x"
+  - tip
+matrix:
+  fast_finish: true
+  allow_failures:
+    - go: tip
+install:
+  - # Do nothing. This is needed to prevent default install action "go get -t -v ./..." from happening here (we want it to happen inside script step).
+script:
+  - go get -t -v ./...
+  - diff -u <(echo -n) <(gofmt -d -s .)
+  - go tool vet .
+  - go test -v ./...
diff --git a/vendor/github.com/russross/blackfriday/v2/LICENSE.txt b/vendor/github.com/russross/blackfriday/v2/LICENSE.txt
new file mode 100644
index 000000000000..2885af3602d8
--- /dev/null
+++ b/vendor/github.com/russross/blackfriday/v2/LICENSE.txt
@@ -0,0 +1,29 @@
+Blackfriday is distributed under the Simplified BSD License:
+
+> Copyright © 2011 Russ Ross
+> All rights reserved.
+>
+> Redistribution and use in source and binary forms, with or without
+> modification, are permitted provided that the following conditions
+> are met:
+>
+> 1.  Redistributions of source code must retain the above copyright
+>     notice, this list of conditions and the following disclaimer.
+>
+> 2.  Redistributions in binary form must reproduce the above
+>     copyright notice, this list of conditions and the following
+>     disclaimer in the documentation and/or other materials provided with
+>     the distribution.
+>
+> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+> "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+> LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+> FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+> COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+> INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+> BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+> LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+> CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+> LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+> ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+> POSSIBILITY OF SUCH DAMAGE.
diff --git a/vendor/github.com/russross/blackfriday/v2/README.md b/vendor/github.com/russross/blackfriday/v2/README.md
new file mode 100644
index 000000000000..d9c08a22fc54
--- /dev/null
+++ b/vendor/github.com/russross/blackfriday/v2/README.md
@@ -0,0 +1,335 @@
+Blackfriday
+[![Build Status][BuildV2SVG]][BuildV2URL]
+[![PkgGoDev][PkgGoDevV2SVG]][PkgGoDevV2URL]
+===========
+
+Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It
+is paranoid about its input (so you can safely feed it user-supplied
+data), it is fast, it supports common extensions (tables, smart
+punctuation substitutions, etc.), and it is safe for all utf-8
+(unicode) input.
+
+HTML output is currently supported, along with Smartypants
+extensions.
+
+It started as a translation from C of [Sundown][3].
+
+
+Installation
+------------
+
+Blackfriday is compatible with modern Go releases in module mode.
+With Go installed:
+
+    go get github.com/russross/blackfriday/v2
+
+will resolve and add the package to the current development module,
+then build and install it. Alternatively, you can achieve the same
+if you import it in a package:
+
+    import "github.com/russross/blackfriday/v2"
+
+and `go get` without parameters.
+
+Legacy GOPATH mode is unsupported.
+
+
+Versions
+--------
+
+Currently maintained and recommended version of Blackfriday is `v2`. It's being
+developed on its own branch: https://github.com/russross/blackfriday/tree/v2 and the
+documentation is available at
+https://pkg.go.dev/github.com/russross/blackfriday/v2.
+
+It is `go get`-able in module mode at `github.com/russross/blackfriday/v2`.
+
+Version 2 offers a number of improvements over v1:
+
+* Cleaned up API
+* A separate call to [`Parse`][4], which produces an abstract syntax tree for
+  the document
+* Latest bug fixes
+* Flexibility to easily add your own rendering extensions
+
+Potential drawbacks:
+
+* Our benchmarks show v2 to be slightly slower than v1. Currently in the
+  ballpark of around 15%.
+* API breakage. If you can't afford modifying your code to adhere to the new API
+  and don't care too much about the new features, v2 is probably not for you.
+* Several bug fixes are trailing behind and still need to be forward-ported to
+  v2. See issue [#348](https://github.com/russross/blackfriday/issues/348) for
+  tracking.
+
+If you are still interested in the legacy `v1`, you can import it from
+`github.com/russross/blackfriday`. Documentation for the legacy v1 can be found
+here: https://pkg.go.dev/github.com/russross/blackfriday.
+
+
+Usage
+-----
+
+For the most sensible markdown processing, it is as simple as getting your input
+into a byte slice and calling:
+
+```go
+output := blackfriday.Run(input)
+```
+
+Your input will be parsed and the output rendered with a set of most popular
+extensions enabled. If you want the most basic feature set, corresponding with
+the bare Markdown specification, use:
+
+```go
+output := blackfriday.Run(input, blackfriday.WithNoExtensions())
+```
+
+### Sanitize untrusted content
+
+Blackfriday itself does nothing to protect against malicious content. If you are
+dealing with user-supplied markdown, we recommend running Blackfriday's output
+through HTML sanitizer such as [Bluemonday][5].
+
+Here's an example of simple usage of Blackfriday together with Bluemonday:
+
+```go
+import (
+    "github.com/microcosm-cc/bluemonday"
+    "github.com/russross/blackfriday/v2"
+)
+
+// ...
+unsafe := blackfriday.Run(input)
+html := bluemonday.UGCPolicy().SanitizeBytes(unsafe)
+```
+
+### Custom options
+
+If you want to customize the set of options, use `blackfriday.WithExtensions`,
+`blackfriday.WithRenderer` and `blackfriday.WithRefOverride`.
+
+### `blackfriday-tool`
+
+You can also check out `blackfriday-tool` for a more complete example
+of how to use it. Download and install it using:
+
+    go get github.com/russross/blackfriday-tool
+
+This is a simple command-line tool that allows you to process a
+markdown file using a standalone program.  You can also browse the
+source directly on github if you are just looking for some example
+code:
+
+* <https://github.com/russross/blackfriday-tool>
+
+Note that if you have not already done so, installing
+`blackfriday-tool` will be sufficient to download and install
+blackfriday in addition to the tool itself. The tool binary will be
+installed in `$GOPATH/bin`.  This is a statically-linked binary that
+can be copied to wherever you need it without worrying about
+dependencies and library versions.
+
+### Sanitized anchor names
+
+Blackfriday includes an algorithm for creating sanitized anchor names
+corresponding to a given input text. This algorithm is used to create
+anchors for headings when `AutoHeadingIDs` extension is enabled. The
+algorithm has a specification, so that other packages can create
+compatible anchor names and links to those anchors.
+
+The specification is located at https://pkg.go.dev/github.com/russross/blackfriday/v2#hdr-Sanitized_Anchor_Names.
+
+[`SanitizedAnchorName`](https://pkg.go.dev/github.com/russross/blackfriday/v2#SanitizedAnchorName) exposes this functionality, and can be used to
+create compatible links to the anchor names generated by blackfriday.
+This algorithm is also implemented in a small standalone package at
+[`github.com/shurcooL/sanitized_anchor_name`](https://pkg.go.dev/github.com/shurcooL/sanitized_anchor_name). It can be useful for clients
+that want a small package and don't need full functionality of blackfriday.
+
+
+Features
+--------
+
+All features of Sundown are supported, including:
+
+*   **Compatibility**. The Markdown v1.0.3 test suite passes with
+    the `--tidy` option.  Without `--tidy`, the differences are
+    mostly in whitespace and entity escaping, where blackfriday is
+    more consistent and cleaner.
+
+*   **Common extensions**, including table support, fenced code
+    blocks, autolinks, strikethroughs, non-strict emphasis, etc.
+
+*   **Safety**. Blackfriday is paranoid when parsing, making it safe
+    to feed untrusted user input without fear of bad things
+    happening. The test suite stress tests this and there are no
+    known inputs that make it crash.  If you find one, please let me
+    know and send me the input that does it.
+
+    NOTE: "safety" in this context means *runtime safety only*. In order to
+    protect yourself against JavaScript injection in untrusted content, see
+    [this example](https://github.com/russross/blackfriday#sanitize-untrusted-content).
+
+*   **Fast processing**. It is fast enough to render on-demand in
+    most web applications without having to cache the output.
+
+*   **Thread safety**. You can run multiple parsers in different
+    goroutines without ill effect. There is no dependence on global
+    shared state.
+
+*   **Minimal dependencies**. Blackfriday only depends on standard
+    library packages in Go. The source code is pretty
+    self-contained, so it is easy to add to any project, including
+    Google App Engine projects.
+
+*   **Standards compliant**. Output successfully validates using the
+    W3C validation tool for HTML 4.01 and XHTML 1.0 Transitional.
+
+
+Extensions
+----------
+
+In addition to the standard markdown syntax, this package
+implements the following extensions:
+
+*   **Intra-word emphasis supression**. The `_` character is
+    commonly used inside words when discussing code, so having
+    markdown interpret it as an emphasis command is usually the
+    wrong thing. Blackfriday lets you treat all emphasis markers as
+    normal characters when they occur inside a word.
+
+*   **Tables**. Tables can be created by drawing them in the input
+    using a simple syntax:
+
+    ```
+    Name    | Age
+    --------|------
+    Bob     | 27
+    Alice   | 23
+    ```
+
+*   **Fenced code blocks**. In addition to the normal 4-space
+    indentation to mark code blocks, you can explicitly mark them
+    and supply a language (to make syntax highlighting simple). Just
+    mark it like this:
+
+        ```go
+        func getTrue() bool {
+            return true
+        }
+        ```
+
+    You can use 3 or more backticks to mark the beginning of the
+    block, and the same number to mark the end of the block.
+
+    To preserve classes of fenced code blocks while using the bluemonday
+    HTML sanitizer, use the following policy:
+
+    ```go
+    p := bluemonday.UGCPolicy()
+    p.AllowAttrs("class").Matching(regexp.MustCompile("^language-[a-zA-Z0-9]+$")).OnElements("code")
+    html := p.SanitizeBytes(unsafe)
+    ```
+
+*   **Definition lists**. A simple definition list is made of a single-line
+    term followed by a colon and the definition for that term.
+
+        Cat
+        : Fluffy animal everyone likes
+
+        Internet
+        : Vector of transmission for pictures of cats
+
+    Terms must be separated from the previous definition by a blank line.
+
+*   **Footnotes**. A marker in the text that will become a superscript number;
+    a footnote definition that will be placed in a list of footnotes at the
+    end of the document. A footnote looks like this:
+
+        This is a footnote.[^1]
+
+        [^1]: the footnote text.
+
+*   **Autolinking**. Blackfriday can find URLs that have not been
+    explicitly marked as links and turn them into links.
+
+*   **Strikethrough**. Use two tildes (`~~`) to mark text that
+    should be crossed out.
+
+*   **Hard line breaks**. With this extension enabled newlines in the input
+    translate into line breaks in the output. This extension is off by default.
+
+*   **Smart quotes**. Smartypants-style punctuation substitution is
+    supported, turning normal double- and single-quote marks into
+    curly quotes, etc.
+
+*   **LaTeX-style dash parsing** is an additional option, where `--`
+    is translated into `&ndash;`, and `---` is translated into
+    `&mdash;`. This differs from most smartypants processors, which
+    turn a single hyphen into an ndash and a double hyphen into an
+    mdash.
+
+*   **Smart fractions**, where anything that looks like a fraction
+    is translated into suitable HTML (instead of just a few special
+    cases like most smartypant processors). For example, `4/5`
+    becomes `<sup>4</sup>&frasl;<sub>5</sub>`, which renders as
+    <sup>4</sup>&frasl;<sub>5</sub>.
+
+
+Other renderers
+---------------
+
+Blackfriday is structured to allow alternative rendering engines. Here
+are a few of note:
+
+*   [github_flavored_markdown](https://pkg.go.dev/github.com/shurcooL/github_flavored_markdown):
+    provides a GitHub Flavored Markdown renderer with fenced code block
+    highlighting, clickable heading anchor links.
+
+    It's not customizable, and its goal is to produce HTML output
+    equivalent to the [GitHub Markdown API endpoint](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode),
+    except the rendering is performed locally.
+
+*   [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt,
+    but for markdown.
+
+*   [LaTeX output](https://gitlab.com/ambrevar/blackfriday-latex):
+    renders output as LaTeX.
+
+*   [bfchroma](https://github.com/Depado/bfchroma/): provides convenience
+    integration with the [Chroma](https://github.com/alecthomas/chroma) code
+    highlighting library. bfchroma is only compatible with v2 of Blackfriday and
+    provides a drop-in renderer ready to use with Blackfriday, as well as
+    options and means for further customization.
+
+*   [Blackfriday-Confluence](https://github.com/kentaro-m/blackfriday-confluence): provides a [Confluence Wiki Markup](https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html) renderer.
+
+*   [Blackfriday-Slack](https://github.com/karriereat/blackfriday-slack): converts markdown to slack message style
+
+
+TODO
+----
+
+*   More unit testing
+*   Improve Unicode support. It does not understand all Unicode
+    rules (about what constitutes a letter, a punctuation symbol,
+    etc.), so it may fail to detect word boundaries correctly in
+    some instances. It is safe on all UTF-8 input.
+
+