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 <[email protected]>
docker · May 29, 2023 · 7f661fa · 7f661fa
1 parent 5be2139
commit 7f661fa
Show file tree

Hide file tree

Showing 71 changed files with 22,970 additions and 111 deletions.
diff --git a/docs/generate/go.mod b/docs/generate/go.mod
diff --git a/docs/generate/tools.go b/docs/generate/tools.go
diff --git a/import.go b/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"
+)
diff --git a/man/go.mod b/man/go.mod
diff --git a/man/tools.go b/man/tools.go
diff --git 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.1}"
+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
@@ -1,36 +1,23 @@
 #!/usr/bin/env bash
 
-set -eu
-
-: "${CLI_DOCS_TOOL_VERSION=v0.5.1}"
+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

diff --git 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.5.1}"
+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
@@ -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
 )
diff --git a/vendor.sum b/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=

diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/.gitignore b/vendor/github.com/cpuguy83/go-md2man/v2/.gitignore
diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/Dockerfile b/vendor/github.com/cpuguy83/go-md2man/v2/Dockerfile
diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/LICENSE.md b/vendor/github.com/cpuguy83/go-md2man/v2/LICENSE.md
diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/Makefile b/vendor/github.com/cpuguy83/go-md2man/v2/Makefile
diff --git a/vendor/github.com/cpuguy83/go-md2man/v2/README.md b/vendor/github.com/cpuguy83/go-md2man/v2/README.md
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