Skip to content

Commit 1b0effd

Browse files
thaJeztahthaJeztah
authored
Merge pull request #19 from crazy-max/flag-type
display flag type and default value in a dedicated columns
2 parents 77df2af + b3ecfe1 commit 1b0effd

File tree

8 files changed

+72
-43
lines changed

8 files changed

+72
-43
lines changed

‎annotation/annotation.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,4 +20,6 @@ const (
2020
// CodeDelimiter specifies the char that will be converted as code backtick.
2121
// Can be used on cmd for inheritance or a specific flag.
2222
CodeDelimiter = "docs.code-delimiter"
23+
// DefaultValue specifies the default value for a flag.
24+
DefaultValue = "docs.default-value"
2325
)

‎clidocstool_md.go‎

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -179,8 +179,8 @@ func mdCmdOutput(cmd *cobra.Command, old string) (string, error) {
179179

180180
if cmd.Flags().HasAvailableFlags() {
181181
fmt.Fprint(b, "### Options\n\n")
182-
fmt.Fprint(b, "| Name | Description |\n")
183-
fmt.Fprint(b, "| --- | --- |\n")
182+
fmt.Fprint(b, "| Name | Type | Default | Description |\n")
183+
fmt.Fprint(b, "| --- | --- | --- | --- |\n")
184184

185185
cmd.Flags().VisitAll(func(f *pflag.Flag) {
186186
if f.Hidden {
@@ -193,19 +193,33 @@ func mdCmdOutput(cmd *cobra.Command, old string) (string, error) {
193193
name = mdMakeLink(name, f.Name, f, isLink)
194194
fmt.Fprintf(b, "%s, ", name)
195195
}
196-
name := "`--" + f.Name
196+
name := "`--" + f.Name + "`"
197+
name = mdMakeLink(name, f.Name, f, isLink)
198+
199+
var ftype string
197200
if f.Value.Type() != "bool" {
198-
name += " " + f.Value.Type()
201+
ftype = "`" + f.Value.Type() + "`"
199202
}
200-
name += "`"
201-
name = mdMakeLink(name, f.Name, f, isLink)
203+
204+
var defval string
205+
if v, ok := f.Annotations[annotation.DefaultValue]; ok && len(v) > 0 {
206+
defval = v[0]
207+
if cd, ok := f.Annotations[annotation.CodeDelimiter]; ok {
208+
defval = strings.ReplaceAll(defval, cd[0], "`")
209+
} else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok {
210+
defval = strings.ReplaceAll(defval, cd, "`")
211+
}
212+
} else if f.DefValue != "" && (f.Value.Type() != "bool" && f.DefValue != "true") && f.DefValue != "[]" {
213+
defval = "`" + f.DefValue + "`"
214+
}
215+
202216
usage := f.Usage
203217
if cd, ok := f.Annotations[annotation.CodeDelimiter]; ok {
204218
usage = strings.ReplaceAll(usage, cd[0], "`")
205219
} else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok {
206220
usage = strings.ReplaceAll(usage, cd, "`")
207221
}
208-
fmt.Fprintf(b, "%s | %s |\n", mdEscapePipe(name), mdEscapePipe(usage))
222+
fmt.Fprintf(b, "%s | %s | %s | %s |\n", mdEscapePipe(name), mdEscapePipe(ftype), mdEscapePipe(defval), mdEscapePipe(usage))
209223
})
210224
fmt.Fprintln(b, "")
211225
}

‎clidocstool_test.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,7 @@ func init() {
106106
buildxBuildFlags.StringArrayP("output", "o", []string{}, `Output destination (format: "type=local,dest=path")`)
107107

108108
buildxBuildFlags.StringArray("platform", []string{}, "Set target platform for build")
109+
buildxBuildFlags.SetAnnotation("platform", annotation.DefaultValue, []string{"local"})
109110

110111
buildxBuildFlags.Bool("push", false, `Shorthand for "--output=type=registry"`)
111112

‎clidocstool_yaml.go‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -269,13 +269,25 @@ func genFlagResult(cmd *cobra.Command, flags *pflag.FlagSet, anchors map[string]
269269

270270
flags.VisitAll(func(flag *pflag.Flag) {
271271
opt = cmdOption{
272-
Option: flag.Name,
273-
ValueType: flag.Value.Type(),
274-
DefaultValue: forceMultiLine(flag.DefValue, defaultValueMaxWidth),
275-
Deprecated: len(flag.Deprecated) > 0,
276-
Hidden: flag.Hidden,
272+
Option: flag.Name,
273+
ValueType: flag.Value.Type(),
274+
Deprecated: len(flag.Deprecated) > 0,
275+
Hidden: flag.Hidden,
277276
}
278277

278+
var defval string
279+
if v, ok := flag.Annotations[annotation.DefaultValue]; ok && len(v) > 0 {
280+
defval = v[0]
281+
if cd, ok := flag.Annotations[annotation.CodeDelimiter]; ok {
282+
defval = strings.ReplaceAll(defval, cd[0], "`")
283+
} else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok {
284+
defval = strings.ReplaceAll(defval, cd, "`")
285+
}
286+
} else {
287+
defval = flag.DefValue
288+
}
289+
opt.DefaultValue = forceMultiLine(defval, defaultValueMaxWidth)
290+
279291
usage := flag.Usage
280292
if cd, ok := flag.Annotations[annotation.CodeDelimiter]; ok {
281293
usage = strings.ReplaceAll(usage, cd[0], "`")

‎fixtures/buildx.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@ Extended build capabilities with BuildKit
1313

1414
### Options
1515

16-
| Name | Description |
17-
| --- | --- |
18-
| `--builder string` | Override the configured builder instance |
16+
| Name | Type | Default | Description |
17+
| --- | --- | --- | --- |
18+
| `--builder` | `string` | | Override the configured builder instance |
1919

2020

2121
<!---MARKER_GEN_END-->

‎fixtures/buildx_build.md‎

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -9,30 +9,30 @@ Start a build
99

1010
### Options
1111

12-
| Name | Description |
13-
| --- | --- |
14-
| [`--add-host stringSlice`](https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host) | Add a custom host-to-IP mapping (format: `host:ip`) |
15-
| `--allow stringSlice` | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) |
16-
| [`--build-arg stringArray`](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg) | Set build-time variables |
17-
| `--builder string` | Override the configured builder instance |
18-
| `--cache-from stringArray` | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) |
19-
| `--cache-to stringArray` | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`) |
20-
| [`--cgroup-parent string`](https://docs.docker.com/engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent) | Optional parent cgroup for the container |
21-
| [`-f`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f), [`--file string`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f) | Name of the Dockerfile (default: `PATH/Dockerfile`) |
22-
| `--iidfile string` | Write the image ID to the file |
23-
| `--label stringArray` | Set metadata for an image |
24-
| `--load` | Shorthand for `--output=type=docker` |
25-
| `--network string` | Set the networking mode for the `RUN` instructions during build |
26-
| `-o`, `--output stringArray` | Output destination (format: `type=local,dest=path`) |
27-
| `--platform stringArray` | Set target platform for build |
28-
| `--push` | Shorthand for `--output=type=registry` |
29-
| `-q`, `--quiet` | Suppress the build output and print image ID on success |
30-
| `--secret stringArray` | Secret file to expose to the build (format: `id=mysecret,src=/local/secret`) |
31-
| `--shm-size string` | Size of `/dev/shm` |
32-
| `--ssh stringArray` | SSH agent socket or keys to expose to the build (format: `default\|<id>[=<socket>\|<key>[,<key>]]`) |
33-
| [`-t`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t), [`--tag stringArray`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t) | Name and optionally a tag (format: `name:tag`) |
34-
| [`--target string`](https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target) | Set the target build stage to build. |
35-
| `--ulimit string` | Ulimit options |
12+
| Name | Type | Default | Description |
13+
| --- | --- | --- | --- |
14+
| [`--add-host`](https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host) | `stringSlice` | | Add a custom host-to-IP mapping (format: `host:ip`) |
15+
| `--allow` | `stringSlice` | | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) |
16+
| [`--build-arg`](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg) | `stringArray` | | Set build-time variables |
17+
| `--builder` | `string` | | Override the configured builder instance |
18+
| `--cache-from` | `stringArray` | | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) |
19+
| `--cache-to` | `stringArray` | | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`) |
20+
| [`--cgroup-parent`](https://docs.docker.com/engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent) | `string` | | Optional parent cgroup for the container |
21+
| [`-f`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f), [`--file`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f) | `string` | | Name of the Dockerfile (default: `PATH/Dockerfile`) |
22+
| `--iidfile` | `string` | | Write the image ID to the file |
23+
| `--label` | `stringArray` | | Set metadata for an image |
24+
| `--load` | | | Shorthand for `--output=type=docker` |
25+
| `--network` | `string` | `default` | Set the networking mode for the `RUN` instructions during build |
26+
| `-o`, `--output` | `stringArray` | | Output destination (format: `type=local,dest=path`) |
27+
| `--platform` | `stringArray` | local | Set target platform for build |
28+
| `--push` | | | Shorthand for `--output=type=registry` |
29+
| `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
30+
| `--secret` | `stringArray` | | Secret file to expose to the build (format: `id=mysecret,src=/local/secret`) |
31+
| `--shm-size` | `string` | | Size of `/dev/shm` |
32+
| `--ssh` | `stringArray` | | SSH agent socket or keys to expose to the build (format: `default\|<id>[=<socket>\|<key>[,<key>]]`) |
33+
| [`-t`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t), [`--tag`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t) | `stringArray` | | Name and optionally a tag (format: `name:tag`) |
34+
| [`--target`](https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target) | `string` | | Set the target build stage to build. |
35+
| `--ulimit` | `string` | | Ulimit options |
3636

3737

3838
<!---MARKER_GEN_END-->

‎fixtures/buildx_stop.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,9 @@ Stop builder instance
55

66
### Options
77

8-
| Name | Description |
9-
| --- | --- |
10-
| `--builder string` | Override the configured builder instance |
8+
| Name | Type | Default | Description |
9+
| --- | --- | --- | --- |
10+
| `--builder` | `string` | | Override the configured builder instance |
1111

1212

1313
<!---MARKER_GEN_END-->

‎fixtures/docker_buildx_build.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -232,7 +232,7 @@ options:
232232
swarm: false
233233
- option: platform
234234
value_type: stringArray
235-
default_value: '[]'
235+
default_value: local
236236
description: Set target platform for build
237237
deprecated: false
238238
hidden: false

0 commit comments

Comments
 (0)