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") Co-authored-by: Sebastiaan van Stijn <github@gone.nl> Signed-off-by: Aleksa Sarai <asarai@suse.de> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
docker · Apr 12, 2024 · b46bfe4 · b46bfe4
1 parent 249b5a4
commit b46bfe4
Show file tree

Hide file tree

Showing 66 changed files with 22,666 additions and 108 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/man/go.mod b/man/go.mod
diff --git a/man/tools.go b/man/tools.go
@@ -1,11 +1,9 @@
-//go:build tools
-// +build tools
+// This is only used to define imports we need for doc generation.
+
+//go:build never
+// +build never
 
 package main
 
-import (
-	_ "github.com/cpuguy83/go-md2man/v2"
-	_ "github.com/spf13/cobra"
-	_ "github.com/spf13/cobra/doc"
-	_ "github.com/spf13/pflag"
-)
+// Used for man page generation.
+import _ "github.com/cpuguy83/go-md2man/v2"
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.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
@@ -1,33 +1,20 @@
 #!/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"
 }
 
-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
 
 (
   set -x

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.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
@@ -9,8 +9,10 @@ go 1.21
 require (
 	dario.cat/mergo v1.0.0
 	github.com/containerd/containerd v1.7.15
+	github.com/cpuguy83/go-md2man/v2 v2.0.4
 	github.com/creack/pty v1.1.21
 	github.com/distribution/reference v0.5.0
+	github.com/docker/cli-docs-tool v0.7.0
 	github.com/docker/distribution v2.8.3+incompatible
 	github.com/docker/docker v26.0.1-0.20240410103514-f9dfd139ec0d+incompatible // master
 	github.com/docker/docker-credential-helpers v0.8.1
@@ -82,6 +84,7 @@ require (
 	github.com/prometheus/common v0.44.0 // indirect
 	github.com/prometheus/procfs v0.12.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
@@ -97,4 +100,5 @@ require (
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20231016165738-49dd2c1f3d0b // indirect
 	google.golang.org/grpc v1.60.1 // indirect
 	google.golang.org/protobuf v1.33.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
diff --git a/vendor.sum b/vendor.sum
@@ -45,6 +45,8 @@ 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/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
+github.com/cpuguy83/go-md2man/v2 v2.0.4 h1:wfIWP927BUkWJb2NmU/kNDYIBTh/ziUX91+lVfRxZq4=
+github.com/cpuguy83/go-md2man/v2 v2.0.4/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=
 github.com/creack/pty v1.1.21/go.mod h1:MOBLtS5ELjhRRrroQr9kyvTxUAFNvYEK993ew/Vr4O4=
@@ -54,6 +56,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.7.0 h1:M2Da98Unz2kz3A5d4yeSGbhyOge2mfYSNjAFt01Rw0M=
+github.com/docker/cli-docs-tool v0.7.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=
@@ -239,6 +243,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/go-internal v1.11.0 h1:cWPaGQEPrBb5/AsnsZesgZZ9yb1OQ+GOISoDNXVBh4M=
 github.com/rogpeppe/go-internal v1.11.0/go.mod h1:ddIwULY96R17DhadqLgMfk9H9tvdUzkipdSkR5nkCZA=
+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/.golangci.yml b/vendor/github.com/cpuguy83/go-md2man/v2/.golangci.yml
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