Skip to content

Commit 8270ed3

Browse files
authored
Merge pull request #53 from dvdksn/fix-root-command-desc-examples
fix: generate long desc and examples for root command
2 parents c6cc9a5 + 7d56538 commit 8270ed3

20 files changed

+182
-55
lines changed

clidocstool.go

+23-23
Original file line numberDiff line numberDiff line change
@@ -88,33 +88,33 @@ func (c *Client) GenAllTree() error {
8888
}
8989

9090
// loadLongDescription gets long descriptions and examples from markdown.
91-
func (c *Client) loadLongDescription(parentCmd *cobra.Command, generator string) error {
92-
for _, cmd := range parentCmd.Commands() {
93-
if cmd.HasSubCommands() {
94-
if err := c.loadLongDescription(cmd, generator); err != nil {
91+
func (c *Client) loadLongDescription(cmd *cobra.Command, generator string) error {
92+
if cmd.HasSubCommands() {
93+
for _, sub := range cmd.Commands() {
94+
if err := c.loadLongDescription(sub, generator); err != nil {
9595
return err
9696
}
9797
}
98-
name := cmd.CommandPath()
99-
if i := strings.Index(name, " "); i >= 0 {
100-
// remove root command / binary name
101-
name = name[i+1:]
102-
}
103-
if name == "" {
104-
continue
105-
}
106-
mdFile := strings.ReplaceAll(name, " ", "_") + ".md"
107-
sourcePath := filepath.Join(c.source, mdFile)
108-
content, err := os.ReadFile(sourcePath)
109-
if os.IsNotExist(err) {
110-
log.Printf("WARN: %s does not exist, skipping Markdown examples for %s docs\n", mdFile, generator)
111-
continue
112-
}
113-
if err != nil {
114-
return err
115-
}
116-
applyDescriptionAndExamples(cmd, string(content))
11798
}
99+
name := cmd.CommandPath()
100+
if i := strings.Index(name, " "); i >= 0 {
101+
// remove root command / binary name
102+
name = name[i+1:]
103+
}
104+
if name == "" {
105+
return nil
106+
}
107+
mdFile := strings.ReplaceAll(name, " ", "_") + ".md"
108+
sourcePath := filepath.Join(c.source, mdFile)
109+
content, err := os.ReadFile(sourcePath)
110+
if os.IsNotExist(err) {
111+
log.Printf("WARN: %s does not exist, skipping Markdown examples for %s docs\n", mdFile, generator)
112+
return nil
113+
}
114+
if err != nil {
115+
return err
116+
}
117+
applyDescriptionAndExamples(cmd, string(content))
118118
return nil
119119
}
120120

clidocstool_man_test.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ func TestGenManTree(t *testing.T) {
4343
c, err := New(Options{
4444
Root: dockerCmd,
4545
SourceDir: tmpdir,
46-
Plugin: true,
46+
Plugin: false,
4747
ManHeader: &doc.GenManHeader{
4848
Title: "DOCKER",
4949
Section: "1",

clidocstool_md_test.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ func TestGenMarkdownTree(t *testing.T) {
3535
c, err := New(Options{
3636
Root: dockerCmd,
3737
SourceDir: tmpdir,
38-
Plugin: true,
38+
Plugin: false,
3939
})
4040
require.NoError(t, err)
4141
require.NoError(t, c.GenMarkdownTree(dockerCmd))

clidocstool_test.go

+6-1
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,11 @@ func setup() {
5454
DisableFlagsInUseLine: true,
5555
}
5656

57+
dockerCmd.PersistentFlags().BoolP("help", "h", false, "Print usage")
58+
dockerCmd.PersistentFlags().MarkShorthandDeprecated("help", "please use --help")
59+
dockerCmd.PersistentFlags().Lookup("help").Hidden = true
60+
dockerCmd.Flags().StringP("host", "H", "unix:///var/run/docker.sock", "Daemon socket to connect to")
61+
5762
attachCmd = &cobra.Command{
5863
Use: "attach [OPTIONS] CONTAINER",
5964
Short: "Attach local standard input, output, and error streams to a running container",
@@ -237,7 +242,7 @@ func TestGenAllTree(t *testing.T) {
237242
c, err := New(Options{
238243
Root: dockerCmd,
239244
SourceDir: tmpdir,
240-
Plugin: true,
245+
Plugin: false,
241246
ManHeader: &doc.GenManHeader{
242247
Title: "DOCKER",
243248
Section: "1",

clidocstool_yaml_test.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ func TestGenYamlTree(t *testing.T) {
3333
c, err := New(Options{
3434
Root: dockerCmd,
3535
SourceDir: tmpdir,
36-
Plugin: true,
36+
Plugin: false,
3737
})
3838
require.NoError(t, err)
3939
require.NoError(t, c.GenYamlTree(dockerCmd))

fixtures/docker-attach.1

-4
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,6 @@ Attach local standard input, output, and error streams to a running container
2121
\fB--detach-keys\fP=""
2222
Override the key sequence for detaching a container
2323

24-
.PP
25-
\fB-h\fP, \fB--help\fP[=false]
26-
help for attach
27-
2824
.PP
2925
\fB--no-stdin\fP[=false]
3026
Do not attach STDIN

fixtures/docker-buildx-build.1

-4
Original file line numberDiff line numberDiff line change
@@ -49,10 +49,6 @@ Start a build
4949
\fB-f\fP, \fB--file\fP=""
5050
Name of the Dockerfile (default: "PATH/Dockerfile")
5151

52-
.PP
53-
\fB-h\fP, \fB--help\fP[=false]
54-
help for build
55-
5652
.PP
5753
\fB--iidfile\fP=""
5854
Write the image ID to the file

fixtures/docker-buildx-dial-stdio.1

-4
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,6 @@ Proxy current stdio streams to builder instance
1717

1818

1919
.SH OPTIONS
20-
.PP
21-
\fB-h\fP, \fB--help\fP[=false]
22-
help for dial-stdio
23-
2420
.PP
2521
\fB--platform\fP=""
2622
Target platform: this is used for node selection

fixtures/docker-buildx-install.1

-6
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,6 @@ docker-buildx-install - Install buildx as a 'docker builder' alias
1616
Install buildx as a 'docker builder' alias
1717

1818

19-
.SH OPTIONS
20-
.PP
21-
\fB-h\fP, \fB--help\fP[=false]
22-
help for install
23-
24-
2519
.SH OPTIONS INHERITED FROM PARENT COMMANDS
2620
.PP
2721
\fB--builder\fP=""

fixtures/docker-buildx-stop.1

-6
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,6 @@ docker-buildx-stop - Stop builder instance
1616
Stop builder instance
1717

1818

19-
.SH OPTIONS
20-
.PP
21-
\fB-h\fP, \fB--help\fP[=false]
22-
help for stop
23-
24-
2519
.SH OPTIONS INHERITED FROM PARENT COMMANDS
2620
.PP
2721
\fB--builder\fP=""

fixtures/docker-buildx.1

-4
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,6 @@ Extended build capabilities with BuildKit
2121
\fB--builder\fP=""
2222
Override the configured builder instance
2323

24-
.PP
25-
\fB-h\fP, \fB--help\fP[=false]
26-
help for buildx
27-
2824

2925
.SH SEE ALSO
3026
.PP

fixtures/docker.1

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
.nh
2+
.TH "DOCKER" "1" "Jan 2020" "Docker Community" "Docker User Manuals"
3+
4+
.SH NAME
5+
.PP
6+
docker - A self-sufficient runtime for containers
7+
8+
9+
.SH SYNOPSIS
10+
.PP
11+
\fBdocker [OPTIONS] COMMAND [ARG...]\fP
12+
13+
14+
.SH DESCRIPTION
15+
.PP
16+
A self-sufficient runtime for containers
17+
18+
19+
.SH OPTIONS
20+
.PP
21+
\fB-H\fP, \fB--host\fP="unix:///var/run/docker.sock"
22+
Daemon socket to connect to
23+
24+
25+
.SH SEE ALSO
26+
.PP
27+
\fBdocker-attach(1)\fP, \fBdocker-buildx(1)\fP

fixtures/docker.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# docker
2+
3+
<!---MARKER_GEN_START-->
4+
A self-sufficient runtime for containers
5+
6+
### Subcommands
7+
8+
| Name | Description |
9+
|:----------------------|:------------------------------------------------------------------------------|
10+
| [`attach`](attach.md) | Attach local standard input, output, and error streams to a running container |
11+
| [`buildx`](buildx.md) | Docker Buildx |
12+
13+
14+
### Options
15+
16+
| Name | Type | Default | Description |
17+
|:---------------|:---------|:------------------------------|:----------------------------|
18+
| `-H`, `--host` | `string` | `unix:///var/run/docker.sock` | Daemon socket to connect to |
19+
20+
21+
<!---MARKER_GEN_END-->
22+

fixtures/docker.yaml

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
command: docker
2+
short: A self-sufficient runtime for containers
3+
long: A self-sufficient runtime for containers
4+
usage: docker [OPTIONS] COMMAND [ARG...]
5+
cname:
6+
- docker attach
7+
- docker buildx
8+
clink:
9+
- docker_attach.yaml
10+
- docker_buildx.yaml
11+
options:
12+
- option: help
13+
value_type: bool
14+
default_value: "false"
15+
description: Print usage
16+
deprecated: false
17+
hidden: true
18+
experimental: false
19+
experimentalcli: false
20+
kubernetes: false
21+
swarm: false
22+
- option: host
23+
shorthand: H
24+
value_type: string
25+
default_value: unix:///var/run/docker.sock
26+
description: Daemon socket to connect to
27+
deprecated: false
28+
hidden: false
29+
experimental: false
30+
experimentalcli: false
31+
kubernetes: false
32+
swarm: false
33+
deprecated: false
34+
hidden: false
35+
experimental: false
36+
experimentalcli: false
37+
kubernetes: false
38+
swarm: false
39+

fixtures/docker_attach.yaml

+11
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,17 @@ options:
3737
experimentalcli: false
3838
kubernetes: false
3939
swarm: false
40+
inherited_options:
41+
- option: help
42+
value_type: bool
43+
default_value: "false"
44+
description: Print usage
45+
deprecated: false
46+
hidden: true
47+
experimental: false
48+
experimentalcli: false
49+
kubernetes: false
50+
swarm: false
4051
deprecated: false
4152
hidden: false
4253
experimental: false

fixtures/docker_buildx.yaml

+11
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,17 @@ options:
2121
experimentalcli: false
2222
kubernetes: false
2323
swarm: false
24+
inherited_options:
25+
- option: help
26+
value_type: bool
27+
default_value: "false"
28+
description: Print usage
29+
deprecated: false
30+
hidden: true
31+
experimental: false
32+
experimentalcli: false
33+
kubernetes: false
34+
swarm: false
2435
deprecated: false
2536
hidden: false
2637
experimental: false

fixtures/docker_buildx_build.yaml

+10
Original file line numberDiff line numberDiff line change
@@ -374,6 +374,16 @@ inherited_options:
374374
experimentalcli: false
375375
kubernetes: false
376376
swarm: false
377+
- option: help
378+
value_type: bool
379+
default_value: "false"
380+
description: Print usage
381+
deprecated: false
382+
hidden: true
383+
experimental: false
384+
experimentalcli: false
385+
kubernetes: false
386+
swarm: false
377387
deprecated: false
378388
hidden: false
379389
experimental: false

fixtures/docker_buildx_dial-stdio.yaml

+10
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,16 @@ inherited_options:
3434
experimentalcli: false
3535
kubernetes: false
3636
swarm: false
37+
- option: help
38+
value_type: bool
39+
default_value: "false"
40+
description: Print usage
41+
deprecated: false
42+
hidden: true
43+
experimental: false
44+
experimentalcli: false
45+
kubernetes: false
46+
swarm: false
3747
deprecated: false
3848
hidden: false
3949
experimental: false

fixtures/docker_buildx_install.yaml

+10
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,16 @@ inherited_options:
1414
experimentalcli: false
1515
kubernetes: false
1616
swarm: false
17+
- option: help
18+
value_type: bool
19+
default_value: "false"
20+
description: Print usage
21+
deprecated: false
22+
hidden: true
23+
experimental: false
24+
experimentalcli: false
25+
kubernetes: false
26+
swarm: false
1727
deprecated: false
1828
hidden: true
1929
experimental: false

fixtures/docker_buildx_stop.yaml

+10
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,16 @@ inherited_options:
1414
experimentalcli: false
1515
kubernetes: false
1616
swarm: false
17+
- option: help
18+
value_type: bool
19+
default_value: "false"
20+
description: Print usage
21+
deprecated: false
22+
hidden: true
23+
experimental: false
24+
experimentalcli: false
25+
kubernetes: false
26+
swarm: false
1727
deprecated: false
1828
hidden: false
1929
experimental: false

0 commit comments

Comments
 (0)