Skip to content

Commit d225d41

Browse files
DannyBenDannyBen
authored
Merge pull request #422 from DannyBen/add/render-mandoc
Add ability to render man pages and `bashly add render_mandoc` library
2 parents 2b77ac8 + 220ac3a commit d225d41

File tree

36 files changed

+781
-11
lines changed

36 files changed

+781
-11
lines changed

‎.github/workflows/test.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,19 @@ jobs:
2020
- name: Checkout code
2121
uses: actions/checkout@v3
2222

23+
- name: Install OS dependencies
24+
run: sudo apt-get -y install mandoc
25+
26+
# Rush needed for easy installation of stuff
27+
- name: Install rush
28+
run: curl -Ls http://get.dannyb.co/rush/setup | bash
29+
30+
- name: Connect rush repo
31+
run: rush clone dannyben --shallow --default
32+
33+
- name: Install pandoc
34+
run: rush get pandoc
35+
2336
# libyaml needed for Ruby's YAML library
2437
- name: Install OS dependencies
2538
run: sudo apt-get -y install libyaml-dev

‎lib/bashly/commands/render.rb‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
require 'filewatcher'
2+
require 'date' # for use by templates
23

34
module Bashly
45
module Commands
@@ -11,8 +12,11 @@ class Render < Base
1112
param 'SOURCE', <<~HELP
1213
An ID to an internal templates source, or a path to a custom templates directory.
1314
14-
Available IDs (note the leading colon):
15+
A leading colon (:) denotes an internal ID.
16+
17+
Available IDs:
1518
- :markdown - render markdown documents for each command.
19+
- :mandoc - render man pages for each command.
1620
HELP
1721

1822
param 'TARGET', 'Output directory'

‎lib/bashly/extensions/string.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ def for_markdown
88
end
99

1010
def nl2br
11-
gsub("\n", "<br>\n")
11+
gsub("\n", " \n")
1212
end
1313

1414
def indent(offset)

‎lib/bashly/libraries/libraries.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,20 @@ render_markdown:
6969
7070
m`$ bashly render templates/markdown docs`
7171
72+
render_mandoc:
73+
help: Copy the mandoc templates to your project, allowing you to customize the man documentation output.
74+
skip_src_check: true
75+
files:
76+
- source: "render/mandoc/mandoc.gtx"
77+
target: "templates/mandoc/mandoc.gtx"
78+
- source: "render/mandoc/render.rb"
79+
target: "templates/mandoc/render.rb"
80+
post_install_message: |
81+
Note that this template requires pandoc.
82+
Generate your man pages by running:
83+
84+
m`$ bashly render templates/mandoc docs`
85+
7286
settings:
7387
help: Copy a sample settings.yml file to your project, allowing you to customize some bashly options.
7488
skip_src_check: true

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

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# Reference: https://linux.die.net/man/5/pandoc_markdown
2+
3+
if version
4+
> % {{ full_name.tr(' ', '-') }}(1) Version {{ version }} | {{ summary }}
5+
else
6+
> % {{ full_name.tr(' ', '-') }}(1) | {{ summary }}
7+
end
8+
> % {{ ENV['AUTHORS'] }}
9+
> % {{ Date.today.strftime "%B %Y" }}
10+
>
11+
12+
> NAME
13+
> ==================================================
14+
>
15+
> **{{ full_name }}** - {{ summary }}
16+
>
17+
18+
> SYNOPSIS
19+
> ==================================================
20+
>
21+
> {{ usage_string.gsub(/^#{full_name}/, "**#{full_name}**") }}
22+
>
23+
24+
> DESCRIPTION
25+
> ==================================================
26+
>
27+
> {{ help.for_markdown }}
28+
>
29+
30+
if default
31+
> - *Default Command*
32+
end
33+
if alt.any?
34+
> - Alias: **{{ alt.join ', ' }}**
35+
end
36+
if extensible
37+
if extensible.is_a? String
38+
> - Extensible: **{{ extensible }}**
39+
else
40+
> - *Extensible*
41+
end
42+
end
43+
>
44+
45+
if commands.any?
46+
grouped_commands.each do |group, commands|
47+
> {{ group.gsub(/:$/, '').upcase }}
48+
> ==================================================
49+
>
50+
commands.each do |subcommand|
51+
> **{{ subcommand.full_name }}**(1)
52+
> : {{ subcommand.summary.for_markdown }}
53+
>
54+
end
55+
>
56+
end
57+
end
58+
59+
if args.any?
60+
> ARGUMENTS
61+
> ==================================================
62+
>
63+
args.each do |arg|
64+
> **{{ arg.name.upcase }}**
65+
> : {{ arg.help.for_markdown }}
66+
>
67+
if arg.required
68+
> - *Required*
69+
end
70+
if arg.repeatable
71+
> - *Repeatable*
72+
end
73+
if arg.default
74+
> - Default Value: **{{ arg.default }}**
75+
end
76+
if arg.allowed
77+
> - Allowed Values: **{{ arg.allowed.join(', ') }}**
78+
end
79+
>
80+
end
81+
82+
if catch_all.label && catch_all.help
83+
> **{{ catch_all.label }}**
84+
> : {{ catch_all.help&.for_markdown }}
85+
>
86+
87+
if catch_all.required?
88+
> - *Required*
89+
>
90+
end
91+
end
92+
end
93+
94+
if flags.any?
95+
> OPTIONS
96+
> ==================================================
97+
>
98+
flags.each do |flag|
99+
> **{{ flag.usage_string }}**
100+
> : {{ flag.help.for_markdown }}
101+
>
102+
103+
if flag.required
104+
> - *Required*
105+
end
106+
if flag.repeatable
107+
> - *Repeatable*
108+
end
109+
if flag.default
110+
> - Default Value: **{{ flag.default }}**
111+
end
112+
if flag.allowed
113+
> - Allowed Values: **{{ flag.allowed.join(', ') }}**
114+
end
115+
if flag.conflicts
116+
> - Conflicts With: **{{ flag.conflicts.join(', ') }}**
117+
end
118+
>
119+
end
120+
end
121+
122+
if dependencies.any?
123+
> DEPENDENCIES
124+
> ==================================================
125+
>
126+
dependencies.each do |dependency|
127+
> **{{ dependency.commands.join ', ' }}**
128+
>
129+
> :{{ dependency.help&.indent(4)&.for_markdown }}
130+
>
131+
end
132+
end
133+
134+
if public_environment_variables.any?
135+
> ENVIRONMENT VARIABLES
136+
> ==================================================
137+
>
138+
public_environment_variables.each do |environment_variable|
139+
> **{{ environment_variable.name.upcase }}**
140+
>
141+
> :{{ environment_variable.help.indent(4).for_markdown }}
142+
>
143+
144+
if environment_variable.required
145+
> - *Required*
146+
end
147+
if environment_variable.default
148+
> - Default Value: **{{ environment_variable.default }}**
149+
end
150+
>
151+
end
152+
end
153+
154+
if examples
155+
> EXAMPLES
156+
> ==================================================
157+
>
158+
> ~~~
159+
examples.each do |example|
160+
> {{ example.for_markdown }}
161+
>
162+
end
163+
> ~~~
164+
end
165+
166+

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# render script - mandoc
2+
3+
# Load the GTX template
4+
template = "#{source}/mandoc.gtx"
5+
gtx = GTX.load_file template
6+
7+
# Define a reusable code block for rendering a man page for a command
8+
save_manpage = lambda { |command|
9+
mdfile = "#{target}/#{command.full_name.tr(' ', '-')}.md"
10+
manfile = "#{target}/#{command.full_name.tr(' ', '-')}.1"
11+
save mdfile, gtx.parse(command)
12+
13+
cmd = %[pandoc -f markdown-smart -s --to man "#{mdfile}" > "#{manfile}"]
14+
15+
success = system "#{cmd}"
16+
raise "Failed running pandoc\nMake sure the following command succeeds and try again:\n\n #{cmd}" unless success
17+
18+
say "g`saved` #{manfile}"
19+
20+
system %[man "#{manfile}"] if ENV['PREVIEW'] == command.full_name
21+
}
22+
23+
# Render the main command
24+
save_manpage.call command
25+
26+
# Render all subcommands
27+
command.deep_commands.reject(&:private).each do |subcommand|
28+
save_manpage.call subcommand
29+
end

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,8 @@ if examples
4343
> ```bash
4444
> {{ example }}
4545
> ```
46+
>
4647
end
47-
>
4848
end
4949

5050
# === Dependencies

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# render script
1+
# render script - markdown
22

33
# Load the GTX template
44
template = "#{source}/markdown.gtx"

‎spec/approvals/cli/add/list‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,10 @@ render_markdown
3434
Copy the markdown templates to your project, allowing you to customize the
3535
markdown documentation output.
3636

37+
render_mandoc
38+
Copy the mandoc templates to your project, allowing you to customize the man
39+
documentation output.
40+
3741
settings
3842
Copy a sample settings.yml file to your project, allowing you to customize
3943
some bashly options.

‎spec/approvals/cli/render/help‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,11 @@ Parameters:
1616
An ID to an internal templates source, or a path to a custom templates
1717
directory.
1818

19-
Available IDs (note the leading colon):
19+
A leading colon (:) denotes an internal ID.
20+
21+
Available IDs:
2022
- :markdown - render markdown documents for each command.
23+
- :mandoc - render man pages for each command.
2124

2225
TARGET
2326
Output directory

0 commit comments

Comments
 (0)