Skip to content

Commit 7054ea7

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 5e6e789 commit 7054ea7

File tree

5 files changed

+205
-0
lines changed

5 files changed

+205
-0
lines changed

‎cmd/loop/docs.go‎

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

‎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)