Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit749694b

Browse files
authored
fix: Standardize and wrap example descriptions at 80 chars (#2894)
1 parent50e8a27 commit749694b

12 files changed

+223
-103
lines changed

‎cli/configssh.go

Lines changed: 10 additions & 9 deletions
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
iferr!=nil {

‎cli/dotfiles.go

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,17 @@ import (
1818
)
1919

2020
funcdotfiles()*cobra.Command {
21-
var (
22-
symlinkDirstring
23-
)
21+
varsymlinkDirstring
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] git@github.com: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 git@github.com:example/dotfiles.git",
30+
},
31+
),
2932
RunE:func(cmd*cobra.Command,args []string)error {
3033
var (
3134
dotfilesRepoDir="dotfiles"

‎cli/parameters.go

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,13 @@ import (
1010

1111
funcparameters()*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

Lines changed: 22 additions & 22 deletions
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 theworkspace to alocal Unix socket
47-
48-
`+cliui.Styles.Code.Render("$ coder port-forward <workspace> --unix ./local.sock:~/remote.sock")+`
49-
50-
- Forward a Unix socket in theworkspace to a local TCP port
51-
52-
`+cliui.Styles.Code.Render("$ coder port-forward <workspace> --unix 8080:~/remote.sock")+`
53-
54-
- Portforwardmultiple 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 onyour 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
iferr!=nil {

‎cli/root.go

Lines changed: 40 additions & 9 deletions
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
funcversionCmd()*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
varstr 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+
typeexamplestruct {
379+
Descriptionstring
380+
Commandstring
381+
}
382+
383+
// formatExamples formats the exampels as width wrapped bulletpoint
384+
// descriptions with the command underneath.
385+
funcformatExamples(examples...example)string {
386+
wrap:=cliui.Styles.Wrap.Copy()
387+
wrap.PaddingLeft(4)
388+
varsb strings.Builder
389+
fori,e:=rangeexamples {
390+
iflen(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+
ifi<len(examples)-1 {
398+
_,_=sb.WriteString("\n\n")
399+
}
400+
}
401+
returnsb.String()
402+
}
403+
373404
// FormatCobraError colorizes and adds "--help" docs to cobra commands.
374405
funcFormatCobraError(errerror,cmd*cobra.Command)string {
375406
helpErrMsg:=fmt.Sprintf("Run '%s --help' for usage.",cmd.CommandPath())

‎cli/root_internal_test.go

Lines changed: 66 additions & 0 deletions
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+
funcTest_formatExamples(t*testing.T) {
10+
t.Parallel()
11+
12+
tests:= []struct {
13+
namestring
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:=rangetests {
52+
tt:=tt
53+
t.Run(tt.name,func(t*testing.T) {
54+
t.Parallel()
55+
56+
got:=formatExamples(tt.examples...)
57+
iflen(tt.wantMatches)==0 {
58+
require.Empty(t,got)
59+
}else {
60+
for_,want:=rangett.wantMatches {
61+
require.Contains(t,got,want)
62+
}
63+
}
64+
})
65+
}
66+
}

‎cli/root_test.go

Lines changed: 1 addition & 2 deletions
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

Lines changed: 23 additions & 10 deletions
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
iferr!=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
iferr!=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
iferr!=nil {

‎cli/templates.go

Lines changed: 14 additions & 12 deletions
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

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,7 @@ import (
99
)
1010

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

3735
funcuserSingle()*cobra.Command {
38-
var (
39-
columns []string
40-
)
36+
varcolumns []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
iferr!=nil {

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp