From bb503ddd80c532436fe5cc622f15ff8ffe74df33 Mon Sep 17 00:00:00 2001 From: Justin Chadwell Date: Mon, 27 Mar 2023 15:39:42 +0100 Subject: [PATCH] docs: add auto-generated sections to buildctl.md Signed-off-by: Justin Chadwell --- Makefile | 10 ++++- README.md | 2 +- docker-bake.hcl | 16 ++++++- docs/generate.go | 76 ++++++++++++++++++++++++++++++++ docs/{ => reference}/buildctl.md | 45 ++++++++++++++++--- hack/dockerfiles/docs.Dockerfile | 54 +++++++++++++++++++++++ 6 files changed, 193 insertions(+), 10 deletions(-) create mode 100644 docs/generate.go rename docs/{ => reference}/buildctl.md (79%) create mode 100644 hack/dockerfiles/docs.Dockerfile diff --git a/Makefile b/Makefile index 3830307cb..8ea26187c 100644 --- a/Makefile +++ b/Makefile @@ -62,8 +62,12 @@ validate-generated-files: validate-doctoc: $(BUILDX_CMD) bake validate-doctoc +.PHONY: validate-docs +validate-docs: + $(BUILDX_CMD) bake validate-docs + .PHONY: validate-all -validate-all: test lint validate-vendor validate-generated-files validate-doctoc +validate-all: test lint validate-vendor validate-generated-files validate-doctoc validate-docs .PHONY: vendor vendor: @@ -84,3 +88,7 @@ authors: .PHONY: doctoc doctoc: $(BUILDX_CMD) bake doctoc + +.PHONY: docs +docs: + $(BUILDX_CMD) bake docs \ No newline at end of file diff --git a/README.md b/README.md index ca23ffc37..eba841711 100644 --- a/README.md +++ b/README.md @@ -128,7 +128,7 @@ $ brew install buildkit To build BuildKit from source, see [`.github/CONTRIBUTING.md`](./.github/CONTRIBUTING.md). -For a `buildctl` reference, see [this document](./docs/buildctl.md). +For a `buildctl` reference, see [this document](./docs/reference/buildctl.md). ### Starting the `buildkitd` daemon diff --git a/docker-bake.hcl b/docker-bake.hcl index 6d60a138f..1030c5144 100644 --- a/docker-bake.hcl +++ b/docker-bake.hcl @@ -75,7 +75,7 @@ target "integration-tests-base" { } group "validate" { - targets = ["lint", "validate-vendor", "validate-doctoc", "validate-generated-files", "validate-shfmt"] + targets = ["lint", "validate-vendor", "validate-doctoc", "validate-generated-files", "validate-shfmt", "validate-docs"] } target "lint" { @@ -119,6 +119,13 @@ target "validate-authors" { output = ["type=cacheonly"] } +target "validate-docs" { + inherits = ["_common"] + dockerfile = "./hack/dockerfiles/docs.Dockerfile" + target = "validate" + output = ["type=cacheonly"] +} + target "vendor" { inherits = ["_common"] dockerfile = "./hack/dockerfiles/vendor.Dockerfile" @@ -153,3 +160,10 @@ target "authors" { target = "update" output = ["."] } + +target "docs" { + inherits = ["_common"] + dockerfile = "./hack/dockerfiles/docs.Dockerfile" + target = "update" + output = ["./docs"] +} diff --git a/docs/generate.go b/docs/generate.go new file mode 100644 index 000000000..4b710371e --- /dev/null +++ b/docs/generate.go @@ -0,0 +1,76 @@ +package main + +import ( + "bytes" + "fmt" + "io/fs" + "os" + "os/exec" + "path/filepath" + "regexp" + + "github.com/pkg/errors" +) + +func main() { + re := regexp.MustCompile("(?s)(.*?)\n") + + err := filepath.Walk("./docs", func(path string, stat fs.FileInfo, err error) error { + if err != nil { + return err + } + if stat.IsDir() { + return nil + } + if filepath.Ext(path) != ".md" { + return nil + } + + data, err := os.ReadFile(path) + if err != nil { + return err + } + + dataNew := re.ReplaceAllFunc(data, func(match []byte) []byte { + groups := re.FindStringSubmatch(string(match)) + stdout := bytes.NewBuffer(nil) + fmt.Fprintf(stdout, "\n", groups[1]) + fmt.Fprintf(stdout, "```\n") + cmd := exec.Cmd{ + Path: "/bin/sh", + Args: []string{"sh", "-c", groups[1]}, + Stdout: stdout, + } + err = cmd.Start() + if err != nil { + err = errors.Wrapf(err, "could not start command %s", groups[1]) + return nil + } + err = cmd.Wait() + if err != nil { + err = errors.Wrapf(err, "could not run command %s", groups[1]) + return nil + } + fmt.Fprintf(stdout, "```\n") + fmt.Fprintf(stdout, "\n") + + return stdout.Bytes() + }) + if err != nil { + return err + } + + if !bytes.Equal(data, dataNew) { + fmt.Println(path) + if err := os.WriteFile(path, dataNew, stat.Mode()); err != nil { + return err + } + } + + return nil + }) + if err != nil { + fmt.Println(err) + os.Exit(1) + } +} diff --git a/docs/buildctl.md b/docs/reference/buildctl.md similarity index 79% rename from docs/buildctl.md rename to docs/reference/buildctl.md index bd95c2752..14cfcd598 100644 --- a/docs/buildctl.md +++ b/docs/reference/buildctl.md @@ -2,6 +2,7 @@ `buildctl` is the command-line interface to `buildkitd`. + ``` NAME: buildctl - build utility @@ -10,14 +11,15 @@ USAGE: buildctl [global options] command [command options] [arguments...] VERSION: - 0.0.0+unknown + v0.0.0+unknown COMMANDS: - du disk usage - prune clean up build cache - build, b build - debug debug utilities - help, h Shows a list of commands or help for one command + du disk usage + prune clean up build cache + prune-histories clean up build histories + build, b build + debug debug utilities + help, h Shows a list of commands or help for one command GLOBAL OPTIONS: --debug enable debug output in logs @@ -31,6 +33,7 @@ GLOBAL OPTIONS: --help, -h show help --version, -v print the version ``` + ## Connecting @@ -45,9 +48,37 @@ Practically, that normally will be one of: Synopsis: + ``` -buildctl build --frontend dockerfile.v0 --opt target=foo --opt build-arg:foo=bar --local context=. --local dockerfile=. --output type=image,name=docker.io/username/image,push=true +NAME: + buildctl build - build + +USAGE: + + To build and push an image using Dockerfile: + $ buildctl build --frontend dockerfile.v0 --opt target=foo --opt build-arg:foo=bar --local context=. --local dockerfile=. --output type=image,name=docker.io/username/image,push=true + + +OPTIONS: + --output value, -o value Define exports for build result, e.g. --output type=image,name=docker.io/username/image,push=true + --progress value Set type of progress (auto, plain, tty). Use plain to show container output (default: "auto") + --trace value Path to trace file. Defaults to no tracing. + --local value Allow build access to the local directory + --oci-layout value Allow build access to the local OCI layout + --frontend value Define frontend used for build + --opt value Define custom options for frontend, e.g. --opt target=foo --opt build-arg:foo=bar + --no-cache Disable cache for all the vertices + --export-cache value Export build cache, e.g. --export-cache type=registry,ref=example.com/foo/bar, or --export-cache type=local,dest=path/to/dir + --import-cache value Import build cache, e.g. --import-cache type=registry,ref=example.com/foo/bar, or --import-cache type=local,src=path/to/dir + --secret value Secret value exposed to the build. Format id=secretname,src=filepath + --allow value Allow extra privileged entitlement, e.g. network.host, security.insecure + --ssh value Allow forwarding SSH agent to the builder. Format default|[=|[,]] + --metadata-file value Output build metadata (e.g., image digest) to a file as JSON + --source-policy-file value Read source policy file from a JSON file + --ref-file value Write build ref to a file + ``` + `buildctl build` uses a buildkit daemon `buildkitd` to drive a build. diff --git a/hack/dockerfiles/docs.Dockerfile b/hack/dockerfiles/docs.Dockerfile new file mode 100644 index 000000000..104da1bd9 --- /dev/null +++ b/hack/dockerfiles/docs.Dockerfile @@ -0,0 +1,54 @@ +# syntax=docker/dockerfile:1 + +ARG GO_VERSION=1.20 + +FROM golang:${GO_VERSION}-alpine${ALPINE_VERSION} AS golatest + +FROM golatest AS buildctl +WORKDIR /src +ENV CGO_ENABLED=0 +ARG TARGETPLATFORM +RUN --mount=target=. \ + --mount=target=/root/.cache,type=cache \ + --mount=target=/go/pkg/mod,type=cache \ + go build -mod=vendor -o /usr/bin/buildctl ./cmd/buildctl + +FROM golatest AS docsgen +WORKDIR /src +ENV CGO_ENABLED=0 +RUN --mount=target=. \ + --mount=target=/root/.cache,type=cache \ + --mount=target=/go/pkg/mod,type=cache \ + go build -mod=vendor -o /out/docsgen ./docs/generate.go + +FROM alpine AS gen +RUN apk add --no-cache rsync git +WORKDIR /src +COPY --from=docsgen /out/docsgen /usr/bin +COPY --from=buildctl /usr/bin/buildctl /usr/bin/ +RUN --mount=target=/context \ + --mount=target=.,type=tmpfs <&2 'ERROR: Docs result differs. Please update with "make docs"' + git status --porcelain -- docs/ + exit 1 +fi +EOT