Skip to content

Commit a650f4d

Browse files
committed
switch to cli-docs-tool for yaml docs generation
Signed-off-by: CrazyMax <[email protected]> switch to cli-docs-tool and validate yamldocs Signed-off-by: CrazyMax <[email protected]>
1 parent 76a2a19 commit a650f4d

16 files changed

Lines changed: 162 additions & 683 deletions

File tree

.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: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,21 @@ jobs:
3232
uses: docker/bake-action@v1
3333
with:
3434
targets: ${{ matrix.target }}
35+
36+
validate-make:
37+
runs-on: ubuntu-latest
38+
strategy:
39+
fail-fast: false
40+
matrix:
41+
target:
42+
- yamldocs # ensure yamldocs target runs fine
43+
steps:
44+
-
45+
name: Checkout
46+
uses: actions/checkout@v2
47+
with:
48+
fetch-depth: 0
49+
-
50+
name: Run
51+
run: |
52+
make -f docker.Makefile ${{ matrix.target }}

.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 & 1 deletion
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

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: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,9 @@ the place to edit them.
2828

2929
The docs in the general repo are open-source and we appreciate
3030
your feedback and pull requests!
31+
32+
# Generate docs
33+
34+
```shell
35+
$ make -f docker.Makefile yamldocs
36+
```

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+
}

docs/go.mod

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
module github.com/docker/cli/docs
2+
3+
// dummy go.mod to avoid dealing with dependencies specific
4+
// to docs generation and not really part of the project.
5+
6+
go 1.16
7+
8+
//require (
9+
// github.com/docker/cli v0.0.0+incompatible
10+
// github.com/docker/cli-docs-tool v0.3.0
11+
//)
12+
//
13+
//replace github.com/docker/cli v0.0.0+incompatible => ../

docs/tools.go

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
// +build tools
2+
3+
package main
4+
5+
import (
6+
_ "github.com/docker/cli-docs-tool"
7+
)

docs/yaml/Dockerfile

Lines changed: 0 additions & 4 deletions
This file was deleted.

0 commit comments

Comments
 (0)