Skip to content

Commit fb7cd10

Browse files
DannyBenDannyBen
authored
Merge pull request #640 from DannyBen/add/render-markdown-github
Add `markdown_github` render template
2 parents 8987058 + 754ca50 commit fb7cd10

File tree

9 files changed

+258
-6
lines changed

9 files changed

+258
-6
lines changed

‎lib/bashly/commands/render.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ def run
5252

5353
def show_list
5454
RenderSource.internal.each_value do |source|
55-
say "g`:#{source.selector.to_s.ljust 10}` #{source.summary}"
55+
say "g`:#{source.selector.to_s.ljust 16}` #{source.summary}"
5656
end
5757
end
5858

‎lib/bashly/libraries/render/mandoc/summary.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Render man pages for your script
1+
Render man pages

‎lib/bashly/libraries/render/markdown/summary.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Render markdown documents for your script
1+
Render markdown documents

‎lib/bashly/libraries/render/markdown_github/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Render GitHub markdown
2+
3+
Render GitHub-compatible markdown documents for your script.
4+
5+
## Usage
6+
7+
```bash
8+
# Generate all documents to the ./docs directory
9+
$ bashly render :markdown_github docs
10+
11+
# Generate on change, and show one of the files
12+
$ bashly render :markdown_github docs --watch --show index.md
13+
```
14+
15+
The differences between this template and the `:markdown` template are:
16+
17+
- Links to sub-command files include the `.md` extension.
18+
- The main file is named `README.md` instead of `index.md`.
19+
20+
## Supported custom definitions
21+
22+
Add these definitions to your `bashly.yml` to render them in your
23+
markdown:
24+
25+
### Footer: `x_markdown_footer`
26+
27+
Add additional sections to your man pages. This field is expected
28+
to be in markdown format.
29+
30+
#### Example
31+
32+
```yaml
33+
x_markdown_footer: |-
34+
# ISSUE TRACKER
35+
36+
Report issues at <https://github.com/lanalang/smallville>
37+
```

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

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# === Header
2+
3+
> # {{ full_name }}
4+
>
5+
> {{ help.for_markdown }}
6+
>
7+
8+
attributes = version || alt.any? || default || extensible
9+
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
25+
>
26+
end
27+
28+
# === Usage
29+
30+
> ## Usage
31+
>
32+
> ```bash
33+
> {{ usage_string.for_markdown }}
34+
> ```
35+
>
36+
37+
# === Examples
38+
39+
if examples
40+
> ## Examples
41+
>
42+
examples.each do |example|
43+
> ```bash
44+
> {{ example }}
45+
> ```
46+
>
47+
end
48+
end
49+
50+
# === Dependencies
51+
52+
if dependencies.any?
53+
> ## Dependencies
54+
>
55+
dependencies.each do |dependency|
56+
> #### *{{ dependency.commands.join ', ' }}*
57+
>
58+
> {{ dependency.help&.for_markdown }}
59+
>
60+
end
61+
end
62+
63+
# === Environment Variables
64+
65+
if visible_environment_variables.any?
66+
> ## Environment Variables
67+
>
68+
visible_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
87+
end
88+
end
89+
90+
# === Commands
91+
92+
if commands.any?
93+
grouped_commands.each do |group, commands|
94+
> ## {{ group.gsub(/:$/, '') }}
95+
>
96+
commands.each do |subcommand|
97+
> - [{{ subcommand.name }}]({{ subcommand.full_name.gsub(' ', '%20') }}.md) - {{ subcommand.summary.for_markdown }}
98+
end
99+
>
100+
end
101+
end
102+
103+
# === Arguments
104+
105+
if args.any?
106+
> ## Arguments
107+
>
108+
args.each do |arg|
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+
>
145+
end
146+
end
147+
end
148+
149+
# === Flags
150+
151+
if flags.any?
152+
> ## Options
153+
>
154+
flags.each do |flag|
155+
attributes = flag.required || flag.repeatable || flag.default ||
156+
flag.allowed || flag.conflicts || flag.needs
157+
158+
> #### *{{ flag.usage_string }}*
159+
>
160+
> {{ flag.help.for_markdown }}
161+
>
162+
163+
if attributes
164+
> | Attributes | &nbsp;
165+
> |-----------------|-------------
166+
if flag.required
167+
> | Required: | ✓ Yes
168+
end
169+
if flag.repeatable
170+
> | Repeatable: | ✓ Yes
171+
end
172+
if flag.default
173+
> | Default Value: | {{ flag.default }}
174+
end
175+
if flag.allowed
176+
> | Allowed Values: | {{ flag.allowed.join(', ') }}
177+
end
178+
if flag.conflicts
179+
> | Conflicts With: | *{{ flag.conflicts.join(', ') }}*
180+
end
181+
if flag.needs
182+
> | Needs: | *{{ flag.needs.join(', ') }}*
183+
end
184+
>
185+
end
186+
end
187+
end
188+
189+
= x_markdown_footer&.for_manpage
190+
>

‎lib/bashly/libraries/render/markdown_github/render.rb‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# render script - markdown
2+
require 'gtx'
3+
4+
# for previewing only (not needed for rendering)
5+
require 'tty-markdown'
6+
7+
# Load the GTX template
8+
template = "#{source}/markdown.gtx"
9+
gtx = GTX.load_file template
10+
11+
# Render the file for the main command
12+
save "#{target}/README.md", gtx.parse(command)
13+
14+
# Render a file for each subcommand
15+
command.deep_commands.reject(&:private).each do |subcommand|
16+
save "#{target}/#{subcommand.full_name}.md", gtx.parse(subcommand)
17+
end
18+
19+
# Show one of the files if requested
20+
if show
21+
file = "#{target}/#{show}"
22+
puts TTY::Markdown.parse_file(file) if File.exist?(file)
23+
end

‎lib/bashly/libraries/render/markdown_github/summary.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Render GitHub-compatible markdown documents

‎spec/approvals/cli/render/list‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
1-
:mandoc Render man pages for your script
2-
:markdown Render markdown documents for your script
1+
:mandoc Render man pages
2+
:markdown Render markdown documents
3+
:markdown_github Render GitHub-compatible markdown documents

‎spec/bashly/render_source_spec.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
describe '::internal' do
88
it 'returns a hash of all internal RenderSource objects' do
99
expect(described_class.internal).to be_a Hash
10-
expect(described_class.internal.keys).to match_array(%i[markdown mandoc])
10+
expect(described_class.internal.keys).to match_array(%i[markdown markdown_github mandoc])
1111
expect(described_class.internal.values).to all(be_a described_class)
1212
end
1313
end

0 commit comments

Comments
 (0)