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 7dc35c0 ("validate manpages target")
Fixes: commit a650f4d ("switch to cli-docs-tool for yaml docs generation")
Signed-off-by: Aleksa Sarai <asarai@suse.de>

import.go

@@ -0,0 +1,17 @@
+// This is only used to define inports 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"
+)

scripts/docs/generate-man.sh

@@ -1,35 +1,18 @@
 #!/usr/bin/env bash
 
-set -eu
-
-: "${MD2MAN_VERSION=v2.0.1}"
+set -Eeuo pipefail
 
 export GO111MODULE=auto
 
-function clean {
-  rm -rf "$buildir"
-}
-
-buildir=$(mktemp -d -t docker-cli-docsgen.XXXXXXXXXX)
-trap clean EXIT
+# temporary "go.mod" to make -modfile= work
+touch go.mod
+# shellcheck disable=SC2064
+trap "rm -f $(pwd)/go.mod" 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")

scripts/docs/generate-md.sh

@@ -1,36 +1,24 @@
 #!/usr/bin/env bash
 
-set -eu
-
-: "${CLI_DOCS_TOOL_VERSION=v0.5.1}"
+set -Eeuo pipefail
 
 export GO111MODULE=auto
 
 function clean {
-  rm -rf "$buildir"
   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
-)
+# temporary "go.mod" to make -modfile= work
+touch go.mod
+# shellcheck disable=SC2064
+trap "rm -f $(pwd)/go.mod" EXIT
+
+# 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

scripts/docs/generate-yaml.sh

@@ -1,33 +1,16 @@
 #!/usr/bin/env bash
 
-set -eu
-
-: "${CLI_DOCS_TOOL_VERSION=v0.5.1}"
+set -Eeuo pipefail
 
 export GO111MODULE=auto
 
-function clean {
-  rm -rf "$buildir"
-}
-
-buildir=$(mktemp -d -t docker-cli-docsgen.XXXXXXXXXX)
-trap clean EXIT
+# temporary "go.mod" to make -modfile= work
+touch go.mod
+# shellcheck disable=SC2064
+trap "rm -f $(pwd)/go.mod" 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

vendor.mod

@@ -11,7 +11,9 @@ replace github.com/docker/docker => github.com/docker/docker v24.0.0-rc.2.0.2023
 
 require (
 	github.com/containerd/containerd v1.6.21
+	github.com/cpuguy83/go-md2man/v2 v2.0.2
 	github.com/creack/pty v1.1.18
+	github.com/docker/cli-docs-tool v0.5.1
 	github.com/docker/distribution v2.8.2+incompatible
 	github.com/docker/docker v24.0.0-rc.2.0.20230506131059-88f4bf4ae4ba+incompatible // replaced; this is master / v25.0.0-dev; see replace rule above.
 	github.com/docker/docker-credential-helpers v0.7.0
@@ -70,6 +72,7 @@ require (
 	github.com/prometheus/common v0.37.0 // indirect
 	github.com/prometheus/procfs v0.8.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
@@ -79,4 +82,5 @@ require (
 	google.golang.org/genproto v0.0.0-20220706185917-7780775163c4 // indirect
 	google.golang.org/grpc v1.50.1 // indirect
 	google.golang.org/protobuf v1.28.1 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

vendor.sum

@@ -85,6 +85,7 @@ github.com/cockroachdb/logtags v0.0.0-20190617123548-eb05cc24525f/go.mod h1:i/u9
 github.com/containerd/containerd v1.6.21 h1:eSTAmnvDKRPWan+MpSSfNyrtleXd86ogK9X8fMWpe/Q=
 github.com/containerd/containerd v1.6.21/go.mod h1:apei1/i5Ux2FzrK6+DM/suEsGuK/MeVOfy8tR2q7Wnw=
 github.com/coreos/go-systemd/v22 v22.3.2/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
+github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
 github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/creack/pty v1.1.18 h1:n56/Zwd5o6whRC5PMGretI4IdRLlmBXYNjScPaBgsbY=
@@ -93,6 +94,8 @@ github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/denisenkom/go-mssqldb v0.0.0-20191128021309-1d7a30a10f73/go.mod h1:xbL0rPBG9cCiLr28tMa8zpbdarY27NDyej4t/EjAShU=
+github.com/docker/cli-docs-tool v0.5.1 h1:jIk/cCZurZERhALPVKhqlNxTQGxn2kcI+56gE57PQXg=
+github.com/docker/cli-docs-tool v0.5.1/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.2+incompatible h1:T3de5rq0dB1j30rp0sA2rER+m322EBzniBPB6ZIzuh8=
 github.com/docker/distribution v2.8.2+incompatible/go.mod h1:J2gT2udsDAN96Uj4KfcMRqY0/ypR+oyYUYmja8H+y+w=
@@ -350,6 +353,7 @@ github.com/rivo/uniseg v0.2.0 h1:S1pD9weZBuJdFmowNwbpi7BJ8TNftyUImj/0WQi72jY=
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rogpeppe/fastuuid v1.2.0/go.mod h1:jVj6XXZzXRy/MSR5jhDC/2q6DgLz+nrA6LYCDYWNEvQ=
 github.com/rogpeppe/go-internal v1.3.0/go.mod h1:M8bDsm7K2OlrFYOpmOWEs/qY81heoFRclV5y23lUDJ4=
+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=