Skip to content

Commit cb3921e

Browse files
authored
Merge branch 'main' into main
2 parents 69089c2 + 6d6ab09 commit cb3921e

File tree

8 files changed

+67
-54
lines changed

8 files changed

+67
-54
lines changed

README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,3 +82,7 @@ greet [GLOBAL OPTIONS] [command [COMMAND OPTIONS]] [ARGUMENTS...]
8282
```
8383

8484
````
85+
86+
## Examples
87+
Some examples of the cli generated using this markdown
88+
* https://woodpecker-ci.org/docs/cli

docs.go

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ func ToTabularMarkdown(cmd *cli.Command, appPath string) (string, error) {
9797
// ToTabularToFileBetweenTags creates a tabular markdown documentation for the `*App` and updates the file between
9898
// the tags in the file. The function errors if either parsing or writing of the string fails.
9999
func ToTabularToFileBetweenTags(cmd *cli.Command, appPath, filePath string, startEndTags ...string) error {
100-
var start, end = "<!--GENERATED:CLI_DOCS-->", "<!--/GENERATED:CLI_DOCS-->" // default tags
100+
start, end := "<!--GENERATED:CLI_DOCS-->", "<!--/GENERATED:CLI_DOCS-->" // default tags
101101

102102
if len(startEndTags) == 2 {
103103
start, end = startEndTags[0], startEndTags[1]
@@ -127,7 +127,7 @@ func ToTabularToFileBetweenTags(cmd *cli.Command, appPath, filePath string, star
127127
updated := re.ReplaceAll(content, []byte(strings.Join([]string{start, comment, md, end}, "\n")))
128128

129129
// write updated content to file
130-
if err = os.WriteFile(filePath, updated, 0664); err != nil {
130+
if err = os.WriteFile(filePath, updated, 0o664); err != nil {
131131
return err
132132
}
133133

@@ -354,6 +354,7 @@ type (
354354
TakesValue bool
355355
Default string
356356
EnvVars []string
357+
Type string
357358
}
358359
)
359360

@@ -362,10 +363,10 @@ type tabularTemplate struct{}
362363

363364
// PrepareCommands converts CLI commands into a structs for the rendering.
364365
func (tt tabularTemplate) PrepareCommands(commands []*cli.Command, appPath, parentCommandName string, level uint) []cliTabularCommandTemplate {
365-
var result = make([]cliTabularCommandTemplate, 0, len(commands))
366+
result := make([]cliTabularCommandTemplate, 0, len(commands))
366367

367368
for _, cmd := range commands {
368-
var command = cliTabularCommandTemplate{
369+
command := cliTabularCommandTemplate{
369370
AppPath: appPath,
370371
Name: strings.TrimSpace(strings.Join([]string{parentCommandName, cmd.Name}, " ")),
371372
Aliases: cmd.Aliases,
@@ -392,19 +393,20 @@ func (tt tabularTemplate) PrepareCommands(commands []*cli.Command, appPath, pare
392393

393394
// PrepareFlags converts CLI flags into a structs for the rendering.
394395
func (tt tabularTemplate) PrepareFlags(flags []cli.Flag) []cliTabularFlagTemplate {
395-
var result = make([]cliTabularFlagTemplate, 0, len(flags))
396+
result := make([]cliTabularFlagTemplate, 0, len(flags))
396397

397398
for _, appFlag := range flags {
398399
flag, ok := appFlag.(cli.DocGenerationFlag)
399400
if !ok {
400401
continue
401402
}
402403

403-
var f = cliTabularFlagTemplate{
404+
f := cliTabularFlagTemplate{
404405
Usage: tt.PrepareMultilineString(flag.GetUsage()),
405406
EnvVars: flag.GetEnvVars(),
406407
TakesValue: flag.TakesValue(),
407408
Default: getFlagDefaultValue(flag),
409+
Type: flag.TypeName(),
408410
}
409411

410412
if boolFlag, isBool := appFlag.(*cli.BoolFlag); isBool {
@@ -446,7 +448,7 @@ func (tabularTemplate) PrepareMultilineString(s string) string {
446448
}
447449

448450
func (tabularTemplate) Prettify(s string) string {
449-
var max = func(x, y int) int {
451+
max := func(x, y int) int {
450452
if x > y {
451453
return x
452454
}
@@ -457,14 +459,14 @@ func (tabularTemplate) Prettify(s string) string {
457459

458460
// search for tables
459461
for _, rawTable := range regexp.MustCompile(`(?m)^(\|[^\n]+\|\r?\n)((?:\|:?-+:?)+\|)(\n(?:\|[^\n]+\|\r?\n?)*)?$`).FindAllString(s, -1) {
460-
var lines = strings.FieldsFunc(rawTable, func(r rune) bool { return r == '\n' })
462+
lines := strings.FieldsFunc(rawTable, func(r rune) bool { return r == '\n' })
461463

462464
if len(lines) < 3 { // header, separator, body
463465
continue
464466
}
465467

466468
// parse table into the matrix
467-
var matrix = make([][]string, 0, len(lines))
469+
matrix := make([][]string, 0, len(lines))
468470
for _, line := range lines {
469471
items := strings.FieldsFunc(strings.Trim(line, "| "), func(r rune) bool { return r == '|' })
470472

@@ -476,13 +478,13 @@ func (tabularTemplate) Prettify(s string) string {
476478
}
477479

478480
// determine centered columns
479-
var centered = make([]bool, 0, len(matrix[1]))
481+
centered := make([]bool, 0, len(matrix[1]))
480482
for _, cell := range matrix[1] {
481483
centered = append(centered, strings.HasPrefix(cell, ":") && strings.HasSuffix(cell, ":"))
482484
}
483485

484486
// calculate max lengths
485-
var lengths = make([]int, len(matrix[0]))
487+
lengths := make([]int, len(matrix[0]))
486488
for n, row := range matrix {
487489
for i, cell := range row {
488490
if n == 1 {

docs_test.go

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,8 @@ import (
1313
"github.com/urfave/cli/v3"
1414
)
1515

16-
var (
17-
//go:embed testdata
18-
testdata embed.FS
19-
)
16+
//go:embed testdata
17+
var testdata embed.FS
2018

2119
func expectFileContent(t *testing.T, file, got string) {
2220
data, err := testdata.ReadFile(file)

go.mod

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
module github.com/urfave/cli-docs/v3
22

3-
go 1.18
3+
go 1.24.4
44

55
require (
66
github.com/cpuguy83/go-md2man/v2 v2.0.2
7-
github.com/stretchr/testify v1.9.0
8-
github.com/urfave/cli/v3 v3.0.0-alpha9.2
7+
github.com/stretchr/testify v1.10.0
8+
github.com/urfave/cli/v3 v3.4.1
99
)
1010

1111
require (

go.sum

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,10 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
66
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
77
github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
88
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
9-
github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
10-
github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
11-
github.com/urfave/cli/v3 v3.0.0-alpha9.2 h1:CL8llQj3dGRLVQQzHxS+ZYRLanOuhyK1fXgLKD+qV+Y=
12-
github.com/urfave/cli/v3 v3.0.0-alpha9.2/go.mod h1:FnIeEMYu+ko8zP1F9Ypr3xkZMIDqW3DR92yUtY39q1Y=
9+
github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
10+
github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
11+
github.com/urfave/cli/v3 v3.4.1 h1:1M9UOCy5bLmGnuu1yn3t3CB4rG79Rtoxuv1sPhnm6qM=
12+
github.com/urfave/cli/v3 v3.4.1/go.mod h1:FJSKtM/9AiiTOJL4fJ6TbMUkxBXn7GO9guZqoZtpYpo=
1313
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
1414
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
1515
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

markdown_tabular.md.gotmpl

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,20 @@
11
{{ define "flags" }}
2-
| Name | Description | Default value | Environment variables |
3-
|------|-------------|:-------------:|:---------------------:|
2+
{{- $hasEnvVars := false -}}
3+
{{- range . -}}
4+
{{- if and (not $hasEnvVars) .EnvVars -}}
5+
{{- $hasEnvVars = true -}}
6+
{{- end -}}
7+
{{- end }}
8+
| Name | Description | Type | Default value {{ if $hasEnvVars }}| Environment variables {{ end }}|
9+
|------|-------------|------|:-------------:{{ if $hasEnvVars }}|:---------------------:{{ end }}|
410
{{ range $flag := . -}}
511
{{- /**/ -}} | `{{ $flag.Name }}{{ if $flag.TakesValue }}="…"{{ end }}` {{ if $flag.Aliases }}(`{{ join $flag.Aliases "`, `" }}`) {{ end }}
612
{{- /**/ -}} | {{ $flag.Usage }}
13+
{{- /**/ -}} | {{ $flag.Type }}
714
{{- /**/ -}} | {{ if $flag.Default }}`{{ $flag.Default }}`{{ end }}
15+
{{- if $hasEnvVars -}}
816
{{- /**/ -}} | {{ if $flag.EnvVars }}`{{ join $flag.EnvVars "`, `" }}`{{ else }}*none*{{ end }}
17+
{{- end -}}
918
{{- /**/ -}} |
1019
{{ end }}
1120
{{ end }}

testdata/expected-tabular-markdown-custom-app-path.md

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -33,10 +33,10 @@ $ /usr/local/bin [GLOBAL FLAGS] config [COMMAND FLAGS] [ARGUMENTS...]
3333

3434
The following flags are supported:
3535

36-
| Name | Description | Default value | Environment variables |
37-
|-----------------------------|--------------------|:-------------:|:---------------------:|
38-
| `--flag="…"` (`--fl`, `-f`) | | | *none* |
39-
| `--another-flag` (`-b`) | another usage text | `false` | *none* |
36+
| Name | Description | Type | Default value |
37+
|-----------------------------|--------------------|--------|:-------------:|
38+
| `--flag="…"` (`--fl`, `-f`) | | string |
39+
| `--another-flag` (`-b`) | another usage text | bool | `false` |
4040

4141
### `config sub-config` subcommand (aliases: `s`, `ss`)
4242

@@ -50,10 +50,10 @@ $ /usr/local/bin [GLOBAL FLAGS] config sub-config [COMMAND FLAGS] [ARGUMENTS...]
5050

5151
The following flags are supported:
5252

53-
| Name | Description | Default value | Environment variables |
54-
|-------------------------------------|-----------------|:-------------:|:---------------------:|
55-
| `--sub-flag="…"` (`--sub-fl`, `-s`) | | | *none* |
56-
| `--sub-command-flag` (`-s`) | some usage text | `false` | *none* |
53+
| Name | Description | Type | Default value |
54+
|-------------------------------------|-----------------|--------|:-------------:|
55+
| `--sub-flag="…"` (`--sub-fl`, `-s`) | | string |
56+
| `--sub-command-flag` (`-s`) | some usage text | bool | `false` |
5757

5858
### `info` command (aliases: `i`, `in`)
5959

@@ -94,10 +94,10 @@ $ /usr/local/bin [GLOBAL FLAGS] usage [COMMAND FLAGS] [ARGUMENTS...]
9494
9595
The following flags are supported:
9696

97-
| Name | Description | Default value | Environment variables |
98-
|-----------------------------|--------------------|:-------------:|:---------------------:|
99-
| `--flag="…"` (`--fl`, `-f`) | | | *none* |
100-
| `--another-flag` (`-b`) | another usage text | `false` | *none* |
97+
| Name | Description | Type | Default value |
98+
|-----------------------------|--------------------|--------|:-------------:|
99+
| `--flag="…"` (`--fl`, `-f`) | | string |
100+
| `--another-flag` (`-b`) | another usage text | bool | `false` |
101101

102102
### `usage sub-usage` subcommand (aliases: `su`)
103103

@@ -113,6 +113,6 @@ $ /usr/local/bin [GLOBAL FLAGS] usage sub-usage [COMMAND FLAGS] [ARGUMENTS...]
113113

114114
The following flags are supported:
115115

116-
| Name | Description | Default value | Environment variables |
117-
|-----------------------------|-----------------|:-------------:|:---------------------:|
118-
| `--sub-command-flag` (`-s`) | some usage text | `false` | *none* |
116+
| Name | Description | Type | Default value |
117+
|-----------------------------|-----------------|------|:-------------:|
118+
| `--sub-command-flag` (`-s`) | some usage text | bool | `false` |

testdata/expected-tabular-markdown-full.md

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -33,10 +33,10 @@ $ app [GLOBAL FLAGS] config [COMMAND FLAGS] [ARGUMENTS...]
3333

3434
The following flags are supported:
3535

36-
| Name | Description | Default value | Environment variables |
37-
|-----------------------------|--------------------|:-------------:|:---------------------:|
38-
| `--flag="…"` (`--fl`, `-f`) | | | *none* |
39-
| `--another-flag` (`-b`) | another usage text | `false` | *none* |
36+
| Name | Description | Type | Default value |
37+
|-----------------------------|--------------------|--------|:-------------:|
38+
| `--flag="…"` (`--fl`, `-f`) | | string |
39+
| `--another-flag` (`-b`) | another usage text | bool | `false` |
4040

4141
### `config sub-config` subcommand (aliases: `s`, `ss`)
4242

@@ -50,10 +50,10 @@ $ app [GLOBAL FLAGS] config sub-config [COMMAND FLAGS] [ARGUMENTS...]
5050

5151
The following flags are supported:
5252

53-
| Name | Description | Default value | Environment variables |
54-
|-------------------------------------|-----------------|:-------------:|:---------------------:|
55-
| `--sub-flag="…"` (`--sub-fl`, `-s`) | | | *none* |
56-
| `--sub-command-flag` (`-s`) | some usage text | `false` | *none* |
53+
| Name | Description | Type | Default value |
54+
|-------------------------------------|-----------------|--------|:-------------:|
55+
| `--sub-flag="…"` (`--sub-fl`, `-s`) | | string |
56+
| `--sub-command-flag` (`-s`) | some usage text | bool | `false` |
5757

5858
### `info` command (aliases: `i`, `in`)
5959

@@ -94,10 +94,10 @@ $ app [GLOBAL FLAGS] usage [COMMAND FLAGS] [ARGUMENTS...]
9494
9595
The following flags are supported:
9696

97-
| Name | Description | Default value | Environment variables |
98-
|-----------------------------|--------------------|:-------------:|:---------------------:|
99-
| `--flag="…"` (`--fl`, `-f`) | | | *none* |
100-
| `--another-flag` (`-b`) | another usage text | `false` | *none* |
97+
| Name | Description | Type | Default value |
98+
|-----------------------------|--------------------|--------|:-------------:|
99+
| `--flag="…"` (`--fl`, `-f`) | | string |
100+
| `--another-flag` (`-b`) | another usage text | bool | `false` |
101101

102102
### `usage sub-usage` subcommand (aliases: `su`)
103103

@@ -113,6 +113,6 @@ $ app [GLOBAL FLAGS] usage sub-usage [COMMAND FLAGS] [ARGUMENTS...]
113113

114114
The following flags are supported:
115115

116-
| Name | Description | Default value | Environment variables |
117-
|-----------------------------|-----------------|:-------------:|:---------------------:|
118-
| `--sub-command-flag` (`-s`) | some usage text | `false` | *none* |
116+
| Name | Description | Type | Default value |
117+
|-----------------------------|-----------------|------|:-------------:|
118+
| `--sub-command-flag` (`-s`) | some usage text | bool | `false` |

0 commit comments

Comments
 (0)