Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 749694b

Browse files
mafredrimafredri
authored
fix: Standardize and wrap example descriptions at 80 chars (coder#2894)
1 parent 50e8a27 commit 749694b

12 files changed

+223
-103
lines changed

‎cli/configssh.go

+10-9
Original file line numberDiff line numberDiff line change
@@ -141,15 +141,16 @@ func configSSH() *cobra.Command {
141141
Annotations: workspaceCommand,
142142
Use: "config-ssh",
143143
Short: "Populate your SSH config with Host entries for all of your workspaces",
144-
Example: `
145-
- You can use -o (or --ssh-option) so set SSH options to be used for all your
146-
workspaces.
147-
148-
` + cliui.Styles.Code.Render("$ coder config-ssh -o ForwardAgent=yes") + `
149-
150-
- You can use --dry-run (or -n) to see the changes that would be made.
151-
152-
` + cliui.Styles.Code.Render("$ coder config-ssh --dry-run"),
144+
Example: formatExamples(
145+
example{
146+
Description: "You can use -o (or --ssh-option) so set SSH options to be used for all your workspaces",
147+
Command: "coder config-ssh -o ForwardAgent=yes",
148+
},
149+
example{
150+
Description: "You can use --dry-run (or -n) to see the changes that would be made",
151+
Command: "coder config-ssh --dry-run",
152+
},
153+
),
153154
RunE: func(cmd *cobra.Command, args []string) error {
154155
client, err := createClient(cmd)
155156
if err != nil {

‎cli/dotfiles.go

+10-7
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,17 @@ import (
1818
)
1919

2020
func dotfiles() *cobra.Command {
21-
var (
22-
symlinkDir string
23-
)
21+
var symlinkDir string
2422
cmd := &cobra.Command{
25-
Use: "dotfiles [git_repo_url]",
26-
Args: cobra.ExactArgs(1),
27-
Short: "Check out and install a dotfiles repository.",
28-
Example: "coder dotfiles [-y] [email protected]:example/dotfiles.git",
23+
Use: "dotfiles [git_repo_url]",
24+
Args: cobra.ExactArgs(1),
25+
Short: "Check out and install a dotfiles repository.",
26+
Example: formatExamples(
27+
example{
28+
Description: "Check out and install a dotfiles repository without prompts",
29+
Command: "coder dotfiles --yes [email protected]:example/dotfiles.git",
30+
},
31+
),
2932
RunE: func(cmd *cobra.Command, args []string) error {
3033
var (
3134
dotfilesRepoDir = "dotfiles"

‎cli/parameters.go

+7-3
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,13 @@ import (
1010

1111
func parameters() *cobra.Command {
1212
cmd := &cobra.Command{
13-
Short: "List parameters for a given scope",
14-
Example: "coder parameters list workspace my-workspace",
15-
Use: "parameters",
13+
Short: "List parameters for a given scope",
14+
Example: formatExamples(
15+
example{
16+
Command: "coder parameters list workspace my-workspace",
17+
},
18+
),
19+
Use: "parameters",
1620
// Currently hidden as this shows parameter values, not parameter
1721
// schemes. Until we have a good way to distinguish the two, it's better
1822
// not to add confusion or lock ourselves into a certain api.

‎cli/portforward.go

+22-22
Original file line numberDiff line numberDiff line change
@@ -32,28 +32,28 @@ func portForward() *cobra.Command {
3232
Short: "Forward one or more ports from the local machine to the remote workspace",
3333
Aliases: []string{"tunnel"},
3434
Args: cobra.ExactArgs(1),
35-
Example: `
36-
- Port forward a single TCP port from 1234 in the workspace to port 5678 on
37-
your local machine
38-
39-
` + cliui.Styles.Code.Render("$ coder port-forward <workspace> --tcp 5678:1234") + `
40-
41-
- Port forward a single UDP port from port 9000 to port 9000 on your local
42-
machine
43-
44-
` + cliui.Styles.Code.Render("$ coder port-forward <workspace> --udp 9000") + `
45-
46-
- Forward a Unix socket in the workspace to a local Unix socket
47-
48-
` + cliui.Styles.Code.Render("$ coder port-forward <workspace> --unix ./local.sock:~/remote.sock") + `
49-
50-
- Forward a Unix socket in the workspace to a local TCP port
51-
52-
` + cliui.Styles.Code.Render("$ coder port-forward <workspace> --unix 8080:~/remote.sock") + `
53-
54-
- Port forward multiple TCP ports and a UDP port
55-
56-
` + cliui.Styles.Code.Render("$ coder port-forward <workspace> --tcp 8080:8080 --tcp 9000:3000 --udp 5353:53"),
35+
Example: formatExamples(
36+
example{
37+
Description: "Port forward a single TCP port from 1234 in the workspace to port 5678 on your local machine",
38+
Command: "coder port-forward <workspace> --tcp 5678:1234",
39+
},
40+
example{
41+
Description: "Port forward a single UDP port from port 9000 to port 9000 on your local machine",
42+
Command: "coder port-forward <workspace> --udp 9000",
43+
},
44+
example{
45+
Description: "Forward a Unix socket in the workspace to a local Unix socket",
46+
Command: "coder port-forward <workspace> --unix ./local.sock:~/remote.sock",
47+
},
48+
example{
49+
Description: "Forward a Unix socket in the workspace to a local TCP port",
50+
Command: "coder port-forward <workspace> --unix 8080:~/remote.sock",
51+
},
52+
example{
53+
Description: "Port forward multiple TCP ports and a UDP port",
54+
Command: "coder port-forward <workspace> --tcp 8080:8080 --tcp 9000:3000 --udp 5353:53",
55+
},
56+
),
5757
RunE: func(cmd *cobra.Command, args []string) error {
5858
specs, err := parsePortForwards(tcpForwards, udpForwards, unixForwards)
5959
if err != nil {

‎cli/root.go

+40-9
Original file line numberDiff line numberDiff line change
@@ -101,12 +101,16 @@ func Root() *cobra.Command {
101101
_, _ = fmt.Fprintln(cmd.ErrOrStderr())
102102
}
103103
},
104-
105-
Example: ` Start a Coder server.
106-
` + cliui.Styles.Code.Render("$ coder server") + `
107-
108-
Get started by creating a template from an example.
109-
` + cliui.Styles.Code.Render("$ coder templates init"),
104+
Example: formatExamples(
105+
example{
106+
Description: "Start a Coder server",
107+
Command: "coder server",
108+
},
109+
example{
110+
Description: "Get started by creating a template from an example",
111+
Command: "coder templates init",
112+
},
113+
),
110114
}
111115

112116
cmd.AddCommand(
@@ -158,9 +162,8 @@ func Root() *cobra.Command {
158162
// versionCmd prints the coder version
159163
func versionCmd() *cobra.Command {
160164
return &cobra.Command{
161-
Use: "version",
162-
Short: "Show coder version",
163-
Example: "coder version",
165+
Use: "version",
166+
Short: "Show coder version",
164167
RunE: func(cmd *cobra.Command, args []string) error {
165168
var str strings.Builder
166169
_, _ = str.WriteString(fmt.Sprintf("Coder %s", buildinfo.Version()))
@@ -370,6 +373,34 @@ Use "{{.CommandPath}} [command] --help" for more information about a command.
370373
{{end}}`
371374
}
372375

376+
// example represents a standard example for command usage, to be used
377+
// with formatExamples.
378+
type example struct {
379+
Description string
380+
Command string
381+
}
382+
383+
// formatExamples formats the exampels as width wrapped bulletpoint
384+
// descriptions with the command underneath.
385+
func formatExamples(examples ...example) string {
386+
wrap := cliui.Styles.Wrap.Copy()
387+
wrap.PaddingLeft(4)
388+
var sb strings.Builder
389+
for i, e := range examples {
390+
if len(e.Description) > 0 {
391+
_, _ = sb.WriteString(" - " + wrap.Render(e.Description + ":")[4:] + "\n\n ")
392+
}
393+
// We add 1 space here because `cliui.Styles.Code` adds an extra
394+
// space. This makes the code block align at an even 2 or 6
395+
// spaces for symmetry.
396+
_, _ = sb.WriteString(" " + cliui.Styles.Code.Render(fmt.Sprintf("$ %s", e.Command)))
397+
if i < len(examples)-1 {
398+
_, _ = sb.WriteString("\n\n")
399+
}
400+
}
401+
return sb.String()
402+
}
403+
373404
// FormatCobraError colorizes and adds "--help" docs to cobra commands.
374405
func FormatCobraError(err error, cmd *cobra.Command) string {
375406
helpErrMsg := fmt.Sprintf("Run '%s --help' for usage.", cmd.CommandPath())

‎cli/root_internal_test.go

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
package cli
2+
3+
import (
4+
"testing"
5+
6+
"github.com/stretchr/testify/require"
7+
)
8+
9+
func Test_formatExamples(t *testing.T) {
10+
t.Parallel()
11+
12+
tests := []struct {
13+
name string
14+
examples []example
15+
wantMatches []string
16+
}{
17+
{
18+
name: "No examples",
19+
examples: nil,
20+
wantMatches: nil,
21+
},
22+
{
23+
name: "Output examples",
24+
examples: []example{
25+
{
26+
Description: "Hello world",
27+
Command: "echo hello",
28+
},
29+
{
30+
Description: "Bye bye",
31+
Command: "echo bye",
32+
},
33+
},
34+
wantMatches: []string{
35+
"Hello world", "echo hello",
36+
"Bye bye", "echo bye",
37+
},
38+
},
39+
{
40+
name: "No description outputs commands",
41+
examples: []example{
42+
{
43+
Command: "echo hello",
44+
},
45+
},
46+
wantMatches: []string{
47+
"echo hello",
48+
},
49+
},
50+
}
51+
for _, tt := range tests {
52+
tt := tt
53+
t.Run(tt.name, func(t *testing.T) {
54+
t.Parallel()
55+
56+
got := formatExamples(tt.examples...)
57+
if len(tt.wantMatches) == 0 {
58+
require.Empty(t, got)
59+
} else {
60+
for _, want := range tt.wantMatches {
61+
require.Contains(t, got, want)
62+
}
63+
}
64+
})
65+
}
66+
}

‎cli/root_test.go

+1-2
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,9 @@ import (
44
"bytes"
55
"testing"
66

7-
"github.com/coder/coder/buildinfo"
8-
97
"github.com/stretchr/testify/require"
108

9+
"github.com/coder/coder/buildinfo"
1110
"github.com/coder/coder/cli"
1211
"github.com/coder/coder/cli/clitest"
1312
)

‎cli/schedule.go

+23-10
Original file line numberDiff line numberDiff line change
@@ -103,10 +103,15 @@ func scheduleStart() *cobra.Command {
103103
cmd := &cobra.Command{
104104
Annotations: workspaceCommand,
105105
Use: "start <workspace-name> { <start-time> [day-of-week] [location] | manual }",
106-
Example: `start my-workspace 9:30AM Mon-Fri Europe/Dublin`,
107-
Short: "Edit workspace start schedule",
108-
Long: scheduleStartDescriptionLong,
109-
Args: cobra.RangeArgs(2, 4),
106+
Example: formatExamples(
107+
example{
108+
Description: "Set the workspace to start at 9:30am (in Dublin) from Monday to Friday",
109+
Command: "coder schedule start my-workspace 9:30AM Mon-Fri Europe/Dublin",
110+
},
111+
),
112+
Short: "Edit workspace start schedule",
113+
Long: scheduleStartDescriptionLong,
114+
Args: cobra.RangeArgs(2, 4),
110115
RunE: func(cmd *cobra.Command, args []string) error {
111116
client, err := createClient(cmd)
112117
if err != nil {
@@ -151,9 +156,13 @@ func scheduleStop() *cobra.Command {
151156
Annotations: workspaceCommand,
152157
Args: cobra.ExactArgs(2),
153158
Use: "stop <workspace-name> { <duration> | manual }",
154-
Example: `stop my-workspace 2h30m`,
155-
Short: "Edit workspace stop schedule",
156-
Long: scheduleStopDescriptionLong,
159+
Example: formatExamples(
160+
example{
161+
Command: "coder schedule stop my-workspace 2h30m",
162+
},
163+
),
164+
Short: "Edit workspace stop schedule",
165+
Long: scheduleStopDescriptionLong,
157166
RunE: func(cmd *cobra.Command, args []string) error {
158167
client, err := createClient(cmd)
159168
if err != nil {
@@ -194,9 +203,13 @@ func scheduleOverride() *cobra.Command {
194203
Args: cobra.ExactArgs(2),
195204
Annotations: workspaceCommand,
196205
Use: "override-stop <workspace-name> <duration from now>",
197-
Example: "override-stop my-workspace 90m",
198-
Short: "Edit stop time of active workspace",
199-
Long: scheduleOverrideDescriptionLong,
206+
Example: formatExamples(
207+
example{
208+
Command: "coder schedule override-stop my-workspace 90m",
209+
},
210+
),
211+
Short: "Edit stop time of active workspace",
212+
Long: scheduleOverrideDescriptionLong,
200213
RunE: func(cmd *cobra.Command, args []string) error {
201214
overrideDuration, err := parseDuration(args[1])
202215
if err != nil {

‎cli/templates.go

+14-12
Original file line numberDiff line numberDiff line change
@@ -16,18 +16,20 @@ func templates() *cobra.Command {
1616
Use: "templates",
1717
Short: "Create, manage, and deploy templates",
1818
Aliases: []string{"template"},
19-
Example: `
20-
- Create a template for developers to create workspaces
21-
22-
` + cliui.Styles.Code.Render("$ coder templates create") + `
23-
24-
- Make changes to your template, and plan the changes
25-
26-
` + cliui.Styles.Code.Render("$ coder templates plan <name>") + `
27-
28-
- Update the template. Your developers can update their workspaces
29-
30-
` + cliui.Styles.Code.Render("$ coder templates update <name>"),
19+
Example: formatExamples(
20+
example{
21+
Description: "Create a template for developers to create workspaces",
22+
Command: "coder templates create",
23+
},
24+
example{
25+
Description: "Make changes to your template, and plan the changes",
26+
Command: "coder templates plan my-template",
27+
},
28+
example{
29+
Description: "Update the template. Your developers can update their workspaces",
30+
Command: "coder templates update my-template",
31+
},
32+
),
3133
}
3234
cmd.AddCommand(
3335
templateCreate(),

‎cli/userlist.go

+10-10
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,7 @@ import (
99
)
1010

1111
func userList() *cobra.Command {
12-
var (
13-
columns []string
14-
)
12+
var columns []string
1513
cmd := &cobra.Command{
1614
Use: "list",
1715
Aliases: []string{"ls"},
@@ -35,14 +33,16 @@ func userList() *cobra.Command {
3533
}
3634

3735
func userSingle() *cobra.Command {
38-
var (
39-
columns []string
40-
)
36+
var columns []string
4137
cmd := &cobra.Command{
42-
Use: "show <username|user_id|'me'>",
43-
Short: "Show a single user. Use 'me' to indicate the currently authenticated user.",
44-
Example: "coder users show me",
45-
Args: cobra.ExactArgs(1),
38+
Use: "show <username|user_id|'me'>",
39+
Short: "Show a single user. Use 'me' to indicate the currently authenticated user.",
40+
Example: formatExamples(
41+
example{
42+
Command: "coder users show me",
43+
},
44+
),
45+
Args: cobra.ExactArgs(1),
4646
RunE: func(cmd *cobra.Command, args []string) error {
4747
client, err := createClient(cmd)
4848
if err != nil {

0 commit comments

Comments
 (0)