Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: include required tools in source tree
Browse files Browse the repository at this point in the history
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: 7dc35c0 ("validate manpages target")
Fixes: a650f4d ("switch to cli-docs-tool for yaml docs generation")
Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
cyphar committed Dec 16, 2024
1 parent 91d097e commit f006b64
Showing 58 changed files with 22,335 additions and 109 deletions.
13 changes: 0 additions & 13 deletions docs/generate/go.mod

This file was deleted.

8 changes: 0 additions & 8 deletions docs/generate/tools.go

This file was deleted.

15 changes: 0 additions & 15 deletions man/go.mod

This file was deleted.

11 changes: 0 additions & 11 deletions man/tools.go

This file was deleted.

30 changes: 8 additions & 22 deletions scripts/docs/generate-man.sh
Original file line number Diff line number Diff line change
@@ -4,32 +4,18 @@ set -eu

: "${MD2MAN_VERSION=v2.0.5}"

export GO111MODULE=auto

function clean {
rm -rf "$buildir"
function clean() {
rm -f go.mod
}

buildir=$(mktemp -d -t docker-cli-docsgen.XXXXXXXXXX)
export GO111MODULE=auto
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
)
./scripts/vendor init
# 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")
26 changes: 6 additions & 20 deletions scripts/docs/generate-md.sh
Original file line number Diff line number Diff line change
@@ -4,30 +4,16 @@ set -eu

: "${CLI_DOCS_TOOL_VERSION=v0.8.0}"

export GO111MODULE=auto

function clean {
rm -rf "$buildir"
function clean() {
rm -f go.mod
}

buildir=$(mktemp -d -t docker-cli-docsgen.XXXXXXXXXX)
export GO111MODULE=auto
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 dependencies
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
)
./scripts/vendor init
# build docsgen
go build -mod=vendor -modfile=vendor.mod -tags docsgen -o /tmp/docsgen ./docs/generate/generate.go

(
set -x
26 changes: 6 additions & 20 deletions scripts/docs/generate-yaml.sh
Original file line number Diff line number Diff line change
@@ -4,30 +4,16 @@ set -eu

: "${CLI_DOCS_TOOL_VERSION=v0.8.0}"

export GO111MODULE=auto

function clean {
rm -rf "$buildir"
function clean() {
rm -f go.mod
}

buildir=$(mktemp -d -t docker-cli-docsgen.XXXXXXXXXX)
export GO111MODULE=auto
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 dependencies
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
)
./scripts/vendor init
# build docsgen
go build -mod=vendor -modfile=vendor.mod -tags docsgen -o /tmp/docsgen ./docs/generate/generate.go

mkdir -p docs/yaml
set -x
3 changes: 3 additions & 0 deletions vendor.mod
Original file line number Diff line number Diff line change
@@ -65,6 +65,7 @@ require (
github.com/cenkalti/backoff/v4 v4.3.0 // indirect
github.com/cespare/xxhash/v2 v2.3.0 // indirect
github.com/containerd/log v0.1.0 // indirect
github.com/cpuguy83/go-md2man/v2 v2.0.4 // indirect
github.com/docker/go v1.5.1-1.0.20160303222718-d30aec9fd63c // indirect
github.com/docker/go-events v0.0.0-20190806004212-e31b211e4f1c // indirect
github.com/docker/go-metrics v0.0.1 // indirect
@@ -88,6 +89,7 @@ require (
github.com/prometheus/common v0.55.0 // indirect
github.com/prometheus/procfs v0.15.1 // 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.16 // indirect
@@ -102,4 +104,5 @@ require (
google.golang.org/genproto/googleapis/rpc v0.0.0-20241007155032-5fefd90f89a9 // indirect
google.golang.org/grpc v1.67.1 // indirect
google.golang.org/protobuf v1.35.2 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
)
2 changes: 2 additions & 0 deletions vendor.sum
Original file line number Diff line number Diff line change
@@ -36,6 +36,7 @@ github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A=
github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw=
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=
@@ -236,6 +237,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.12.0 h1:exVL4IDcn6na9z1rAb56Vxr+CgyK3nn3O+epU5NdKM8=
github.com/rogpeppe/go-internal v1.12.0/go.mod h1:E+RYuTGaKKdloAfM02xzb0FW3Paa99yedzYV+kq4uf4=
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=
21 changes: 21 additions & 0 deletions vendor/github.com/cpuguy83/go-md2man/v2/LICENSE.md

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

16 changes: 16 additions & 0 deletions vendor/github.com/cpuguy83/go-md2man/v2/md2man/md2man.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit f006b64

Please sign in to comment.