Skip to content

Commit 941233e

Browse files
stariusstarius
committed
cmd/loop: add commands "loop man", "loop markdown"
Produce the documentations in man .1 and markdown formats. The template for markdown was patched to removed column "Environment variables" Upstream PR: urfave/cli-docs#15 Also the input has to be pre-processed to remove nested "help" subcommands from each subcommand to improve readability. Upstream PR: urfave/cli-docs#16
1 parent fee6f9c commit 941233e

File tree

5 files changed

+190
-0
lines changed

5 files changed

+190
-0
lines changed

‎cmd/loop/docs.go‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
package main
2+
3+
import (
4+
"context"
5+
_ "embed"
6+
"fmt"
7+
8+
docs "github.com/urfave/cli-docs/v3"
9+
"github.com/urfave/cli/v3"
10+
)
11+
12+
//go:embed markdown_tabular.md.gotmpl
13+
var markdownTabularDocTemplate string
14+
15+
// We have a copy of this template taken from
16+
// https://github.com/urfave/cli-docs where we remove column
17+
// "Environment variables" if it has no values.
18+
// TODO: remove this when https://github.com/urfave/cli-docs/pull/15
19+
// is merged.
20+
func init() {
21+
docs.MarkdownTabularDocTemplate = markdownTabularDocTemplate
22+
}
23+
24+
var printManCommand = &cli.Command{
25+
Name: "man",
26+
Usage: "prints man file",
27+
Description: "Prints documentation of loop CLI in man format",
28+
Action: printMan,
29+
Hidden: true,
30+
}
31+
32+
func printMan(_ context.Context, cmd *cli.Command) error {
33+
root := filterNestedHelpCommands(cmd.Root())
34+
35+
const userCommandsSection = 1
36+
man, err := docs.ToManWithSection(root, userCommandsSection)
37+
if err != nil {
38+
return fmt.Errorf("failed to produce man: %w", err)
39+
}
40+
41+
fmt.Println(man)
42+
43+
return nil
44+
}
45+
46+
var printMarkdownCommand = &cli.Command{
47+
Name: "markdown",
48+
Usage: "prints markdown file",
49+
Description: "Prints documentation of loop CLI in markdown format",
50+
Action: printMarkdown,
51+
Hidden: true,
52+
}
53+
54+
func printMarkdown(_ context.Context, cmd *cli.Command) error {
55+
root := filterNestedHelpCommands(cmd.Root())
56+
57+
md, err := docs.ToTabularMarkdown(root, "loop")
58+
if err != nil {
59+
return fmt.Errorf("failed to produce man: %w", err)
60+
}
61+
62+
fmt.Println(md)
63+
64+
return nil
65+
}
66+
67+
// filterNestedHelpCommands returns a copy of cmd with nested "help"
68+
// sub-commands removed.
69+
// TODO: remove when https://github.com/urfave/cli-docs/pull/16
70+
func filterNestedHelpCommands(cmd *cli.Command) *cli.Command {
71+
return cloneCommand(cmd, 0)
72+
}
73+
74+
// cloneCommand clones the command, filtering out nested "help" subcommands.
75+
// TODO: remove when https://github.com/urfave/cli-docs/pull/16
76+
func cloneCommand(cmd *cli.Command, depth int) *cli.Command {
77+
if cmd == nil {
78+
return nil
79+
}
80+
81+
cloned := *cmd
82+
if len(cmd.Commands) == 0 {
83+
return &cloned
84+
}
85+
86+
filtered := make([]*cli.Command, 0, len(cmd.Commands))
87+
for _, sub := range cmd.Commands {
88+
if sub == nil {
89+
continue
90+
}
91+
childDepth := depth + 1
92+
if childDepth > 0 && sub.Name == "help" {
93+
continue
94+
}
95+
filtered = append(filtered, cloneCommand(sub, childDepth))
96+
}
97+
98+
cloned.Commands = filtered
99+
return &cloned
100+
}

‎cmd/loop/main.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@ var (
9090
setLiquidityRuleCommand, suggestSwapCommand, setParamsCommand,
9191
getInfoCommand, abandonSwapCommand, reservationsCommands,
9292
instantOutCommand, listInstantOutsCommand,
93+
printManCommand, printMarkdownCommand,
9394
}
9495
)
9596

‎cmd/loop/markdown_tabular.md.gotmpl‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
{{ define "flags" }}
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 }}|
10+
{{ range $flag := . -}}
11+
{{- /**/ -}} | `{{ $flag.Name }}{{ if $flag.TakesValue }}="…"{{ end }}` {{ if $flag.Aliases }}(`{{ join $flag.Aliases "`, `" }}`) {{ end }}
12+
{{- /**/ -}} | {{ $flag.Usage }}
13+
{{- /**/ -}} | {{ $flag.Type }}
14+
{{- /**/ -}} | {{ if $flag.Default }}`{{ $flag.Default }}`{{ end }}
15+
{{- if $hasEnvVars -}}
16+
{{- /**/ -}} | {{ if $flag.EnvVars }}`{{ join $flag.EnvVars "`, `" }}`{{ else }}*none*{{ end }}
17+
{{- end -}}
18+
{{- /**/ -}} |
19+
{{ end }}
20+
{{ end }}
21+
22+
{{ define "command" }}
23+
### `{{ .Name }}` {{ if gt .Level 0 }}sub{{ end }}command{{ if .Aliases }} (aliases: `{{ join .Aliases "`, `" }}`){{ end }}
24+
{{ if .Usage }}
25+
{{ .Usage }}.
26+
{{ end }}
27+
{{ if .UsageText }}
28+
{{ range $line := .UsageText -}}
29+
> {{ $line }}
30+
{{ end -}}
31+
{{ end }}
32+
{{ if .Description }}
33+
{{ .Description }}.
34+
{{ end }}
35+
Usage:
36+
37+
```bash
38+
$ {{ .AppPath }} [GLOBAL FLAGS] {{ .Name }}{{ if .Flags }} [COMMAND FLAGS]{{ end }} {{ if .ArgsUsage }}{{ .ArgsUsage }}{{ else }}[ARGUMENTS...]{{ end }}
39+
```
40+
41+
{{ if .Flags -}}
42+
The following flags are supported:
43+
{{ template "flags" .Flags }}
44+
{{ end -}}
45+
46+
{{ if .SubCommands -}}
47+
{{ range $subCmd := .SubCommands -}}
48+
{{ template "command" $subCmd }}
49+
{{ end -}}
50+
{{ end -}}
51+
{{ end }}
52+
53+
## CLI interface{{ if .Name }} - {{ .Name }}{{ end }}
54+
55+
{{ if .Description }}{{ .Description }}.
56+
{{ end }}
57+
{{ if .Usage }}{{ .Usage }}.
58+
{{ end }}
59+
{{ if .UsageText }}
60+
{{ range $line := .UsageText -}}
61+
> {{ $line }}
62+
{{ end -}}
63+
{{ end }}
64+
Usage:
65+
66+
```bash
67+
$ {{ .AppPath }}{{ if .GlobalFlags }} [GLOBAL FLAGS]{{ end }} [COMMAND] [COMMAND FLAGS] {{ if .ArgsUsage }}{{ .ArgsUsage }}{{ else }}[ARGUMENTS...]{{ end }}
68+
```
69+
70+
{{ if .GlobalFlags }}
71+
Global flags:
72+
73+
{{ template "flags" .GlobalFlags }}
74+
75+
{{ end -}}
76+
{{ if .Commands -}}
77+
{{ range $cmd := .Commands -}}
78+
{{ template "command" $cmd }}
79+
{{ end }}
80+
{{- end }}

‎go.mod‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ require (
3434
github.com/lightningnetwork/lnd/tor v1.1.6
3535
github.com/ory/dockertest/v3 v3.10.0
3636
github.com/stretchr/testify v1.10.0
37+
github.com/urfave/cli-docs/v3 v3.1.0
3738
github.com/urfave/cli/v3 v3.4.1
3839
go.etcd.io/bbolt v1.3.11
3940
golang.org/x/sync v0.12.0
@@ -72,6 +73,7 @@ require (
7273
github.com/coreos/go-semver v0.3.0 // indirect
7374
github.com/coreos/go-systemd v0.0.0-20191104093116-d3cd4ed1dbcf // indirect
7475
github.com/coreos/go-systemd/v22 v22.5.0 // indirect
76+
github.com/cpuguy83/go-md2man/v2 v2.0.2 // indirect
7577
github.com/decred/dcrd/crypto/blake256 v1.0.1 // indirect
7678
github.com/decred/dcrd/lru v1.1.2 // indirect
7779
github.com/docker/cli v28.0.1+incompatible // indirect
@@ -149,6 +151,7 @@ require (
149151
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
150152
github.com/rogpeppe/fastuuid v1.2.0 // indirect
151153
github.com/rogpeppe/go-internal v1.14.1 // indirect
154+
github.com/russross/blackfriday/v2 v2.1.0 // indirect
152155
github.com/sirupsen/logrus v1.9.3 // indirect
153156
github.com/soheilhy/cmux v0.1.5 // indirect
154157
github.com/spf13/pflag v1.0.6 // indirect

‎go.sum‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -736,6 +736,8 @@ github.com/coreos/go-systemd v0.0.0-20191104093116-d3cd4ed1dbcf h1:iW4rZ826su+pq
736736
github.com/coreos/go-systemd v0.0.0-20191104093116-d3cd4ed1dbcf/go.mod h1:F5haX7vjVVG0kc13fIWeqUViNPyEJxv/OmvnBo0Yme4=
737737
github.com/coreos/go-systemd/v22 v22.5.0 h1:RrqgGjYQKalulkV8NGVIfkXQf6YYmOyiJKk8iXXhfZs=
738738
github.com/coreos/go-systemd/v22 v22.5.0/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
739+
github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
740+
github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
739741
github.com/creack/pty v1.1.7/go.mod h1:lj5s0c3V2DBrqTV7llrYr5NG6My20zk30Fl46Y7DoTY=
740742
github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
741743
github.com/creack/pty v1.1.18 h1:n56/Zwd5o6whRC5PMGretI4IdRLlmBXYNjScPaBgsbY=
@@ -1263,6 +1265,8 @@ github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7
12631265
github.com/rs/xid v1.2.1/go.mod h1:+uKXf+4Djp6Md1KODXJxgGQPKngRmWyn10oCKFzNHOQ=
12641266
github.com/rs/zerolog v1.13.0/go.mod h1:YbFCdg8HfsridGWAh22vktObvhZbQsZXe4/zB0OKkWU=
12651267
github.com/rs/zerolog v1.15.0/go.mod h1:xYTKnLHcpfU2225ny5qZjxnj9NvkumZYjJHlAThCjNc=
1268+
github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
1269+
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
12661270
github.com/ruudk/golang-pdf417 v0.0.0-20181029194003-1af4ab5afa58/go.mod h1:6lfFZQK844Gfx8o5WFuvpxWRwnSoipWe/p622j1v06w=
12671271
github.com/ruudk/golang-pdf417 v0.0.0-20201230142125-a7e3863a1245/go.mod h1:pQAZKsJ8yyVxGRWYNEm9oFB8ieLgKFnamEyDmSA0BRk=
12681272
github.com/satori/go.uuid v1.2.0/go.mod h1:dA0hQrYB0VpLJoorglMZABFdXlWrHn1NEOzdhQKdks0=
@@ -1309,6 +1313,8 @@ github.com/tmc/grpc-websocket-proxy v0.0.0-20201229170055-e5319fda7802 h1:uruHq4
13091313
github.com/tmc/grpc-websocket-proxy v0.0.0-20201229170055-e5319fda7802/go.mod h1:ncp9v5uamzpCO7NfCPTXjqaC+bZgJeR0sMTm6dMHP7U=
13101314
github.com/tv42/zbase32 v0.0.0-20160707012821-501572607d02 h1:tcJ6OjwOMvExLlzrAVZute09ocAGa7KqOON60++Gz4E=
13111315
github.com/tv42/zbase32 v0.0.0-20160707012821-501572607d02/go.mod h1:tHlrkM198S068ZqfrO6S8HsoJq2bF3ETfTL+kt4tInY=
1316+
github.com/urfave/cli-docs/v3 v3.1.0 h1:Sa5xm19IpE5gpm6tZzXdfjdFxn67PnEsE4dpXF7vsKw=
1317+
github.com/urfave/cli-docs/v3 v3.1.0/go.mod h1:59d+5Hz1h6GSGJ10cvcEkbIe3j233t4XDqI72UIx7to=
13121318
github.com/urfave/cli/v3 v3.4.1 h1:1M9UOCy5bLmGnuu1yn3t3CB4rG79Rtoxuv1sPhnm6qM=
13131319
github.com/urfave/cli/v3 v3.4.1/go.mod h1:FJSKtM/9AiiTOJL4fJ6TbMUkxBXn7GO9guZqoZtpYpo=
13141320
github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f h1:J9EGpcZtP0E/raorCMxlFGSTBrsSlaDGf3jU/qvAE2c=

0 commit comments

Comments
 (0)