Skip to content

Commit 966a470

Browse files
crazy-maxcrazy-max
committed
switch to cli-docs-tool and validate yamldocs
Signed-off-by: CrazyMax <[email protected]>
1 parent db67d98 commit 966a470

155 files changed

Lines changed: 164 additions & 693 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.dockerignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,11 @@
22
/cli/winresources/versioninfo.json
33
/cli/winresources/*.syso
44
/man/man*/
5-
/docs/yaml/gen/
5+
/docs/yaml/
6+
/docs/vendor/
7+
/docs/go.sum
68
profile.out
79

810
# top-level go.mod is not meant to be checked in
911
/go.mod
12+
/go.sum

‎.github/workflows/validate.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ jobs:
2020
- lint
2121
- shellcheck
2222
- validate-vendor
23+
- update-yamldocs # ensure yamldocs update target runs fine
2324
- update-authors # ensure authors update target runs fine
2425
steps:
2526
-

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ Thumbs.db
1313
/man/man1/
1414
/man/man5/
1515
/man/man8/
16-
/docs/yaml/gen/
1716
profile.out
1817

1918
# top-level go.mod is not meant to be checked in
2019
/go.mod
20+
/go.sum

‎Makefile‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ _:=$(shell ./scripts/warn-outside-container $(MAKECMDGOALS))
1111

1212
.PHONY: clean
1313
clean: ## remove build artifacts
14-
rm -rf ./build/* cli/winresources/rsrc_* ./man/man[1-9] docs/yaml/gen
14+
rm -rf ./build/* cli/winresources/rsrc_* ./man/man[1-9] docs/yaml
1515

1616
.PHONY: test
1717
test: test-unit ## run tests
@@ -70,10 +70,6 @@ authors: ## generate AUTHORS file from git history
7070
manpages: ## generate man pages from go source and markdown
7171
scripts/docs/generate-man.sh
7272

73-
.PHONY: yamldocs
74-
yamldocs: ## generate documentation YAML files consumed by docs repo
75-
scripts/docs/generate-yaml.sh
76-
7773
.PHONY: help
7874
help: ## print this help
7975
@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z0-9_-]+:.*?## / {gsub("\\\\n",sprintf("\n%22c",""), $$2);printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)

‎docker-bake.hcl‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,13 @@ target "update-authors" {
131131
output = ["."]
132132
}
133133

134+
target "update-yamldocs" {
135+
inherits = ["_common"]
136+
dockerfile = "./dockerfiles/Dockerfile.docs"
137+
target = "update"
138+
output = ["./docs/yaml"]
139+
}
140+
134141
target "test" {
135142
target = "test"
136143
output = ["type=cacheonly"]

‎docker.Makefile‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -104,8 +104,12 @@ manpages: build_docker_image ## generate man pages from go source and markdown
104104
$(DOCKER_RUN) -it $(DEV_DOCKER_IMAGE_NAME) make manpages
105105

106106
.PHONY: yamldocs
107-
yamldocs: build_docker_image ## generate documentation YAML files consumed by docs repo
108-
$(DOCKER_RUN) -it $(DEV_DOCKER_IMAGE_NAME) make yamldocs
107+
yamldocs: ## generate documentation YAML files consumed by docs repo
108+
$(eval $@_TMP_OUT := $(shell mktemp -d -t dockercli-output.XXXXXXXXXX))
109+
docker buildx bake --set "*.output=$($@_TMP_OUT)" update-yamldocs
110+
rm -rf ./docs/yaml
111+
cp -R "$($@_TMP_OUT)"/out/* .
112+
rm -rf $($@_TMP_OUT)/*
109113

110114
.PHONY: test ## run unit and e2e tests
111115
test: test-unit test-e2e

‎dockerfiles/Dockerfile.docs‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# syntax=docker/dockerfile:1.3-labs
2+
3+
ARG GO_VERSION=1.16.11
4+
ARG CLI_DOCS_TOOL_VERSION=v0.3.0
5+
6+
FROM golang:${GO_VERSION}-alpine AS base
7+
RUN apk add --no-cache bash git make rsync
8+
WORKDIR /go/src/github.com/docker/cli
9+
ENV GO111MODULE=auto
10+
11+
FROM base AS docsgen
12+
ARG CLI_DOCS_TOOL_VERSION
13+
RUN --mount=target=.,rw \
14+
--mount=type=cache,target=/root/.cache \
15+
--mount=type=cache,target=/go/pkg/mod <<EOT
16+
set -ex
17+
./scripts/vendor init
18+
go mod edit -modfile=vendor.mod -require=github.com/docker/cli-docs-tool@${CLI_DOCS_TOOL_VERSION}
19+
cp docs/tools.go .
20+
./scripts/vendor update
21+
rm -f go.mod
22+
go build -tags docsgen -o /out/docsgen ./docs/generate.go
23+
EOT
24+
25+
FROM base AS gen
26+
COPY --from=docsgen /out/docsgen /usr/bin
27+
RUN --mount=target=/context \
28+
--mount=type=tmpfs,target=. <<EOT
29+
set -e
30+
rsync -a /context/. .
31+
docsgen --source "docs/reference/commandline" --target "/out/docs/yaml"
32+
EOT
33+
34+
FROM scratch AS update
35+
COPY --from=gen /out /out

‎docs/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/vendor
2+
/yaml
3+
/go.sum

‎docs/README.md‎

Lines changed: 8 additions & 0 deletions

‎docs/generate.go‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
// This file is intended for use with "go run"; it isn't really part of the package.
2+
3+
// +build docsgen
4+
5+
package main
6+
7+
import (
8+
"log"
9+
"os"
10+
11+
clidocstool "github.com/docker/cli-docs-tool"
12+
"github.com/docker/cli/cli/command"
13+
"github.com/docker/cli/cli/command/commands"
14+
"github.com/spf13/cobra"
15+
"github.com/spf13/pflag"
16+
)
17+
18+
const defaultSourcePath = "docs/reference/commandline/"
19+
20+
type options struct {
21+
source string
22+
target string
23+
}
24+
25+
func gen(opts *options) error {
26+
log.SetFlags(0)
27+
28+
dockerCLI, err := command.NewDockerCli()
29+
if err != nil {
30+
return err
31+
}
32+
cmd := &cobra.Command{
33+
Use: "docker [OPTIONS] COMMAND [ARG...]",
34+
Short: "The base command for the Docker CLI.",
35+
}
36+
commands.AddCommands(cmd, dockerCLI)
37+
38+
c, err := clidocstool.New(clidocstool.Options{
39+
Root: cmd,
40+
SourceDir: opts.source,
41+
TargetDir: opts.target,
42+
Plugin: false,
43+
})
44+
if err != nil {
45+
return err
46+
}
47+
48+
return c.GenYamlTree(cmd)
49+
}
50+
51+
func run() error {
52+
opts := &options{}
53+
flags := pflag.NewFlagSet(os.Args[0], pflag.ContinueOnError)
54+
flags.StringVar(&opts.source, "source", defaultSourcePath, "Docs source folder")
55+
flags.StringVar(&opts.target, "target", defaultSourcePath, "Docs target folder")
56+
if err := flags.Parse(os.Args[1:]); err != nil {
57+
return err
58+
}
59+
return gen(opts)
60+
}
61+
62+
func main() {
63+
if err := run(); err != nil {
64+
log.Printf("ERROR: %+v", err)
65+
os.Exit(1)
66+
}
67+
}

0 commit comments

Comments
 (0)