Skip to content

Commit 2b77ac8

Browse files
DannyBenDannyBen
authored
Merge pull request #420 from DannyBen/refactor/markdown-template
Refactor markdown template
2 parents a661071 + b1c620a commit 2b77ac8

File tree

28 files changed

+416
-80
lines changed

28 files changed

+416
-80
lines changed

‎lib/bashly/extensions/string.rb‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
class String
22
def sanitize_for_print
3-
gsub("\n", '\\n').gsub('"', '\"')
3+
gsub("\n", '\\n').gsub('"', '\"').gsub('`', '\\\\`')
4+
end
5+
6+
def for_markdown
7+
gsub('<', '\\<').gsub('>', '\\>').nl2br
8+
end
9+
10+
def nl2br
11+
gsub("\n", "<br>\n")
412
end
513

614
def indent(offset)

‎lib/bashly/libraries/render/markdown/markdown.gtx‎

Lines changed: 113 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,36 @@
22

33
> # {{ full_name }}
44
>
5+
> {{ help.for_markdown }}
6+
>
7+
8+
attributes = version || alt.any? || default || extensible
59

6-
if alt.any?
7-
> **Alias:** {{ alt.join ', ' }}
10+
if attributes
11+
> | Attributes | &nbsp;
12+
> |------------------|-------------
13+
if version
14+
> | Version: | {{ version }}
15+
end
16+
if alt.any?
17+
> | Alias: | {{ alt.join ', ' }}
18+
end
19+
if default
20+
> | Default Command: | ✓ Yes
21+
end
22+
if extensible
23+
> | Extensible: | {{ extensible.is_a?(String) ? extensible : "✓ Yes" }}
24+
end
825
>
926
end
1027

11-
> {{ help }}
12-
>
13-
1428
# === Usage
1529

1630
> ## Usage
1731
>
18-
> `{{ usage_string }}`
32+
> ```bash
33+
> {{ usage_string.for_markdown }}
34+
> ```
1935
>
2036

2137
# === Examples
@@ -24,7 +40,9 @@ if examples
2440
> ## Examples
2541
>
2642
examples.each do |example|
27-
> - `{{ example }}`
43+
> ```bash
44+
> {{ example }}
45+
> ```
2846
end
2947
>
3048
end
@@ -35,23 +53,38 @@ if dependencies.any?
3553
> ## Dependencies
3654
>
3755
dependencies.each do |dependency|
38-
> - {{ dependency.commands.join ' or ' }}
56+
> #### *{{ dependency.commands.join ', ' }}*
57+
>
58+
> {{ dependency.help&.for_markdown }}
59+
>
3960
end
40-
>
4161
end
4262

4363
# === Environment Variables
4464

45-
if environment_variables.any?
65+
if public_environment_variables.any?
4666
> ## Environment Variables
4767
>
48-
= "<dl>"
49-
environment_variables.each do |environment_variable|
50-
= " <dt>#{environment_variable.usage_string}</dt>"
51-
= " <dd>#{environment_variable.help}</dd>"
68+
public_environment_variables.each do |environment_variable|
69+
attributes = environment_variable.required || environment_variable.default
70+
71+
> #### *{{ environment_variable.name.upcase }}*
72+
>
73+
> {{ environment_variable.help.for_markdown }}
74+
>
75+
76+
if attributes
77+
> | Attributes | &nbsp;
78+
> |-----------------|-------------
79+
if environment_variable.required
80+
> | Required: | ✓ Yes
81+
end
82+
if environment_variable.default
83+
> | Default Value: | {{ environment_variable.default }}
84+
end
85+
>
86+
end
5287
end
53-
= "</dl>"
54-
>
5588
end
5689

5790
# === Commands
@@ -61,7 +94,7 @@ if commands.any?
6194
> ## {{ group.gsub(/:$/, '') }}
6295
>
6396
commands.each do |subcommand|
64-
> - [{{ subcommand.name }}]({{ subcommand.full_name }}) - {{ subcommand.summary }}
97+
> - [{{ subcommand.name }}]({{ subcommand.full_name }}) - {{ subcommand.summary.for_markdown }}
6598
end
6699
>
67100
end
@@ -72,25 +105,78 @@ end
72105
if args.any?
73106
> ## Arguments
74107
>
75-
= "<dl>"
76108
args.each do |arg|
77-
= " <dt>#{arg.name}</dt>"
78-
= " <dd>#{arg.help}</dd>"
109+
attributes = arg.required || arg.repeatable || arg.default || arg.allowed
110+
111+
> #### *{{ arg.name.upcase }}*
112+
>
113+
> {{ arg.help.for_markdown }}
114+
>
115+
116+
if attributes
117+
> | Attributes | &nbsp;
118+
> |-----------------|-------------
119+
if arg.required
120+
> | Required: | ✓ Yes
121+
end
122+
if arg.repeatable
123+
> | Repeatable: | ✓ Yes
124+
end
125+
if arg.default
126+
> | Default Value: | {{ arg.default }}
127+
end
128+
if arg.allowed
129+
> | Allowed Values: | {{ arg.allowed.join(', ') }}
130+
end
131+
>
132+
end
133+
end
134+
135+
if catch_all.label && catch_all.help
136+
> #### *{{ catch_all.label }}*
137+
>
138+
> {{ catch_all.help&.for_markdown }}
139+
>
140+
if catch_all.required?
141+
> | Attributes | &nbsp;
142+
> |------------|-------------
143+
> | Required: | ✓ Yes
144+
end
79145
end
80-
= "</dl>"
81-
>
82146
end
83147

84148
# === Flags
85149

86150
if flags.any?
87151
> ## Options
88152
>
89-
= "<dl>"
90153
flags.each do |flag|
91-
= " <dt>#{flag.usage_string extended: true}</dt>"
92-
= " <dd>#{flag.help}</dd>"
154+
attributes = flag.required || flag.repeatable || flag.default || flag.allowed || flag.conflicts
155+
156+
> #### *{{ flag.usage_string }}*
157+
>
158+
> {{ flag.help.for_markdown }}
159+
>
160+
161+
if attributes
162+
> | Attributes | &nbsp;
163+
> |-----------------|-------------
164+
if flag.required
165+
> | Required: | ✓ Yes
166+
end
167+
if flag.repeatable
168+
> | Repeatable: | ✓ Yes
169+
end
170+
if flag.default
171+
> | Default Value: | {{ flag.default }}
172+
end
173+
if flag.allowed
174+
> | Allowed Values: | {{ flag.allowed.join(', ') }}
175+
end
176+
if flag.conflicts
177+
> | Conflicts With: | *{{ flag.conflicts.join(', ') }}*
178+
end
179+
>
180+
end
93181
end
94-
= "</dl>"
95-
>
96182
end

‎lib/bashly/views/command/dependencies_filter.gtx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ if dependencies.any?
77
> else
88
> printf "{{ strings[:missing_dependency] % { dependency: dependency.name } }}\n" >&2
99
if dependency.help
10-
> printf "%s\n" "{{ dependency.help }}" >&2
10+
> printf "%s\n" "{{ dependency.help.sanitize_for_print }}" >&2
1111
end
1212
> exit 1
1313
> fi

‎lib/bashly/views/command/footer.gtx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
= view_marker
22

3-
> printf "{{ footer.gsub("\n", '\n').gsub('"', '\"') }}\n"
3+
> printf "{{ footer.sanitize_for_print }}\n"
44
> echo
55
>

‎lib/bashly/views/command/parse_requirements_while.gtx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ if catch_all.enabled?
2727
> ;;
2828

2929
else
30-
> printf "<%= strings[:invalid_flag] %>\n" "$key" >&2
30+
> printf "{{ strings[:invalid_flag] }}\n" "$key" >&2
3131
> exit 1
3232
> ;;
3333

‎lib/bashly/views/command/usage.gtx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
> if [[ -n $long_usage ]]; then
55

66
if summary == help
7-
> printf "{{ caption_string }}\n"
7+
> printf "{{ caption_string.sanitize_for_print }}\n"
88
> echo
99
else
1010
> printf "{{ full_name }}\n"
@@ -14,7 +14,7 @@ else
1414
end
1515

1616
> else
17-
> printf "{{ caption_string }}\n"
17+
> printf "{{ caption_string.sanitize_for_print }}\n"
1818
> echo
1919
> fi
2020
>

‎lib/bashly/views/command/usage_commands.gtx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ command_help_data.each do |group, commands|
77

88
commands.each do |command, info|
99
if info[:help_only]
10-
> [[ -n $long_usage ]] && printf " %s {{ info[:summary] }}\n" "{{ command.ljust(maxlen).color(:command) }}"
10+
> [[ -n $long_usage ]] && printf " %s {{ info[:summary].sanitize_for_print }}\n" "{{ command.ljust(maxlen).color(:command) }}"
1111
else
12-
> printf " %s {{ info[:summary] }}\n" "{{ command.ljust(maxlen).color(:command) }}"
12+
> printf " %s {{ info[:summary].sanitize_for_print }}\n" "{{ command.ljust(maxlen).color(:command) }}"
1313
end
1414
end
1515

‎spec/approvals/rendering/markdown/catch-all-advanced/cli download.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# cli download
2+
3+
Download a file
4+
5+
| Attributes | &nbsp;
6+
|------------------|-------------
7+
| Alias: | d
8+
9+
## Usage
10+
11+
```bash
12+
cli download SOURCE [TARGET] [OPTIONS] [AWS PARAMS...]
13+
```
14+
15+
## Examples
16+
17+
```bash
18+
cli download example.com
19+
```
20+
```bash
21+
cli download example.com ./output -f
22+
```
23+
24+
## Arguments
25+
26+
#### *SOURCE*
27+
28+
URL to download from
29+
30+
| Attributes | &nbsp;
31+
|-----------------|-------------
32+
| Required: | ✓ Yes
33+
34+
#### *TARGET*
35+
36+
Target filename (default: same as source)
37+
38+
#### *AWS PARAMS...*
39+
40+
Additional arguments or flags for AWS CLI
41+
42+
## Options
43+
44+
#### *--force, -f*
45+
46+
Overwrite existing files
47+

‎spec/approvals/rendering/markdown/catch-all-advanced/cli upload.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# cli upload
2+
3+
Upload a file
4+
5+
| Attributes | &nbsp;
6+
|------------------|-------------
7+
| Alias: | u
8+
9+
## Usage
10+
11+
```bash
12+
cli upload FILES...
13+
```
14+

‎spec/approvals/rendering/markdown/catch-all-advanced/index.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# cli
2+
3+
Sample application
4+
5+
| Attributes | &nbsp;
6+
|------------------|-------------
7+
| Version: | 0.1.0
8+
9+
## Usage
10+
11+
```bash
12+
cli COMMAND
13+
```
14+
15+
## Commands
16+
17+
- [download](cli download) - Download a file
18+
- [upload](cli upload) - Upload a file
19+

0 commit comments

Comments
 (0)