Skip to content

Commit 98420de

Browse files
DannyBenDannyBen
committed
- Add render-mandoc man page generation example
1 parent b44b91f commit 98420de

File tree

10 files changed

+362
-7
lines changed

10 files changed

+362
-7
lines changed

‎examples/README.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -51,11 +51,6 @@ Each of these examples demonstrates one aspect or feature of bashly.
5151
- [command-function](command-function#readme) - configuring custom internal function names
5252
- [split-config](split-config#readme) - splitting your `bashly.yml` into several smaller files
5353

54-
## Real-world-like examples
55-
56-
- [docker-like](docker-like#readme) - a sample script with deep commands (like `docker container run`)
57-
- [git-like](git-like#readme) - a sample script with sub-commands similar to git
58-
5954
## Bashly library features
6055

6156
- [config](config#readme) - using the config library for easy access to INI files
@@ -66,7 +61,16 @@ Each of these examples demonstrates one aspect or feature of bashly.
6661
- [validations](validations#readme) - adding argument validation functions
6762
- [hooks](hooks#readme) - adding before/after hooks
6863

69-
## Other Examples
64+
## Real-world-like examples
65+
66+
- [docker-like](docker-like#readme) - a sample script with deep commands (like `docker container run`)
67+
- [git-like](git-like#readme) - a sample script with sub-commands similar to git
68+
69+
## Documentation generation
70+
71+
- [render-mandoc](render-mandoc#readme) - auto-generate man pages for your script
72+
73+
## Other examples
7074

7175
- [heredoc](heredoc#readme) - using heredoc strings
7276
- [heredoc-alt](heredoc-alt#readme) - using heredoc strings in the lib directory

‎examples/dependencies-alt/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ args: none
6060
deps:
6161
- ${deps[git]} = /usr/bin/git
6262
- ${deps[http_client]} = /usr/bin/curl
63-
- ${deps[ruby]} = /home/vagrant/.rbenv/versions/3.2.2/bin/ruby
63+
- ${deps[ruby]} = /home/vagrant/.rbenv/versions/3.1.4/bin/ruby
6464
6565
6666
```

‎examples/render-mandoc/README.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Render Mandoc Example
2+
3+
This example shows how to render man pages from your bashly commands, and how
4+
to use custom properties to add more information to the man page.
5+
6+
This example was generated with:
7+
8+
```bash
9+
$ bashly init --minimal
10+
# ... now edit src/bashly.yml to match the example ...
11+
$ bashly render :mandoc docs
12+
```
13+
14+
-----
15+
16+
## `bashly.yml`
17+
18+
```yaml
19+
name: download
20+
help: Sample application
21+
version: 0.1.0
22+
23+
# Optional, custom properties that are used by the mandoc renderer
24+
x_mandoc_authors: Lana Lang
25+
x_mandoc_footer: |-
26+
# ISSUE TRACKER
27+
28+
Report issues at <https://github.com/lanalang/smallville>
29+
30+
dependencies:
31+
aws-cli: Download from <https://aws.amazon.com/cli/>
32+
33+
args:
34+
- name: source
35+
required: true
36+
allowed: [server1, server2]
37+
repeatable: true
38+
help: Source to download from
39+
- name: target
40+
help: "Target filename (default: same as source)"
41+
42+
flags:
43+
- long: --force
44+
short: -f
45+
help: Overwrite existing files
46+
- long: --debug
47+
short: -d
48+
help: Show debug information
49+
```
50+
51+
52+
53+
## Generated script output
54+
55+
### `$ man docs/download.1 | col -bx`
56+
57+
```shell
58+
download(1) Sample minimal application without commands download(1)
59+
60+
NAME
61+
download - Sample minimal application without commands
62+
63+
SYNOPSIS
64+
download SOURCE... [TARGET] OPTIONS
65+
66+
DESCRIPTION
67+
Sample minimal application without commands
68+
69+
ARGUMENTS
70+
SOURCE Source to download from
71+
72+
• Required
73+
74+
• Repeatable
75+
76+
• Allowed Values: server1, server2
77+
78+
TARGET Target filename (default: same as source)
79+
80+
OPTIONS
81+
--force, -f
82+
Overwrite existing files
83+
84+
--debug, -d
85+
Show debug information
86+
87+
DEPENDENCIES
88+
aws-cli
89+
Download from <https://aws.amazon.com/cli/>
90+
91+
ISSUE TRACKER
92+
Report issues at <https://github.com/lanalang/smallville>
93+
94+
AUTHORS
95+
Lana Lang.
96+
97+
Version 0.1.0 August 2023 download(1)
98+
99+
100+
```
101+
102+
103+

‎examples/render-mandoc/docs/download.1‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
.\" Automatically generated by Pandoc 3.1.6
2+
.\"
3+
.\" Define V font for inline verbatim, using C font in formats
4+
.\" that render this, and otherwise B font.
5+
.ie "\f[CB]x\f[]"x" \{\
6+
. ftr V B
7+
. ftr VI BI
8+
. ftr VB B
9+
. ftr VBI BI
10+
.\}
11+
.el \{\
12+
. ftr V CR
13+
. ftr VI CI
14+
. ftr VB CB
15+
. ftr VBI CBI
16+
.\}
17+
.TH "download" "1" "August 2023" "Version 0.1.0" "Sample minimal application without commands"
18+
.hy
19+
.SH NAME
20+
.PP
21+
\f[B]download\f[R] - Sample minimal application without commands
22+
.SH SYNOPSIS
23+
.PP
24+
\f[B]download\f[R] SOURCE...
25+
[TARGET] OPTIONS
26+
.SH DESCRIPTION
27+
.PP
28+
Sample minimal application without commands
29+
.SH ARGUMENTS
30+
.TP
31+
\f[B]SOURCE\f[R]
32+
Source to download from
33+
.RS
34+
.IP \[bu] 2
35+
\f[I]Required\f[R]
36+
.IP \[bu] 2
37+
\f[I]Repeatable\f[R]
38+
.IP \[bu] 2
39+
Allowed Values: \f[B]server1, server2\f[R]
40+
.RE
41+
.TP
42+
\f[B]TARGET\f[R]
43+
Target filename (default: same as source)
44+
.SH OPTIONS
45+
.TP
46+
\f[B]--force, -f\f[R]
47+
Overwrite existing files
48+
.TP
49+
\f[B]--debug, -d\f[R]
50+
Show debug information
51+
.SH DEPENDENCIES
52+
.TP
53+
\f[B]aws-cli\f[R]
54+
Download from <https://aws.amazon.com/cli/>
55+
.SH ISSUE TRACKER
56+
.PP
57+
Report issues at <https://github.com/lanalang/smallville>
58+
.SH AUTHORS
59+
Lana Lang.

‎examples/render-mandoc/docs/download.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
% download(1) Version 0.1.0 | Sample minimal application without commands
2+
% Lana Lang
3+
% August 2023
4+
5+
NAME
6+
==================================================
7+
8+
**download** - Sample minimal application without commands
9+
10+
SYNOPSIS
11+
==================================================
12+
13+
**download** SOURCE... [TARGET] [OPTIONS]
14+
15+
DESCRIPTION
16+
==================================================
17+
18+
Sample minimal application without commands
19+
20+
21+
ARGUMENTS
22+
==================================================
23+
24+
**SOURCE**
25+
: Source to download from
26+
27+
- *Required*
28+
- *Repeatable*
29+
- Allowed Values: **server1, server2**
30+
31+
**TARGET**
32+
: Target filename (default: same as source)
33+
34+
35+
OPTIONS
36+
==================================================
37+
38+
**--force, -f**
39+
: Overwrite existing files
40+
41+
42+
**--debug, -d**
43+
: Show debug information
44+
45+
46+
DEPENDENCIES
47+
==================================================
48+
49+
**aws-cli**
50+
: Download from \<https://aws.amazon.com/cli/\>
51+
52+
53+
# ISSUE TRACKER
54+
55+
Report issues at <https://github.com/lanalang/smallville>

‎examples/render-mandoc/out.txt‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
download(1) Sample minimal application without commands download(1)
2+
3+
NAME
4+
download - Sample minimal application without commands
5+
6+
SYNOPSIS
7+
download SOURCE... [TARGET] OPTIONS
8+
9+
DESCRIPTION
10+
Sample minimal application without commands
11+
12+
ARGUMENTS
13+
SOURCE Source to download from
14+
15+
• Required
16+
17+
• Repeatable
18+
19+
• Allowed Values: server1, server2
20+
21+
TARGET Target filename (default: same as source)
22+
23+
OPTIONS
24+
--force, -f
25+
Overwrite existing files
26+
27+
--debug, -d
28+
Show debug information
29+
30+
DEPENDENCIES
31+
aws-cli
32+
Download from <https://aws.amazon.com/cli/>
33+
34+
ISSUE TRACKER
35+
Report issues at <https://github.com/lanalang/smallville>
36+
37+
AUTHORS
38+
Lana Lang.
39+
40+
Version 0.1.0 August 2023 download(1)

‎examples/render-mandoc/src/bashly.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: download
2+
help: Sample application
3+
version: 0.1.0
4+
5+
# Optional, custom properties that are used by the mandoc renderer
6+
x_mandoc_authors: Lana Lang
7+
x_mandoc_footer: |-
8+
# ISSUE TRACKER
9+
10+
Report issues at <https://github.com/lanalang/smallville>
11+
12+
dependencies:
13+
aws-cli: Download from <https://aws.amazon.com/cli/>
14+
15+
args:
16+
- name: source
17+
required: true
18+
allowed: [server1, server2]
19+
repeatable: true
20+
help: Source to download from
21+
- name: target
22+
help: "Target filename (default: same as source)"
23+
24+
flags:
25+
- long: --force
26+
short: -f
27+
help: Overwrite existing files
28+
- long: --debug
29+
short: -d
30+
help: Show debug information

‎examples/render-mandoc/test.sh‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#!/usr/bin/env bash
2+
3+
rm -f ./src/*.sh
4+
5+
set -x
6+
7+
bashly render :mandoc docs
8+
9+
### Try Me ###
10+
11+
# when running interactively, you can just run:
12+
#
13+
# man docs/download.1
14+
#
15+
man docs/download.1 | col -bx

‎spec/approvals/examples/render-manpage‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
+ bashly render :mandoc docs
2+
saved docs/download.md
3+
saved docs/download.1
4+
+ PAGER=cat
5+
+ man docs/download.1
6+
download(1) Sample minimal application without commands download(1)
7+
8+
NNAAMMEE
9+
ddoowwnnllooaadd - Sample minimal application without commands
10+
11+
SSYYNNOOPPSSIISS
12+
ddoowwnnllooaadd SOURCE... [TARGET] OPTIONS
13+
14+
DDEESSCCRRIIPPTTIIOONN
15+
Sample minimal application without commands
16+
17+
AARRGGUUMMEENNTTSS
18+
SSOOUURRCCEE Source to download from
19+
20+
• _R_e_q_u_i_r_e_d
21+
22+
• _R_e_p_e_a_t_a_b_l_e
23+
24+
• Allowed Values: sseerrvveerr11,, sseerrvveerr22
25+
26+
TTAARRGGEETT Target filename (default: same as source)
27+
28+
OOPPTTIIOONNSS
29+
----ffoorrccee,, --ff
30+
Overwrite existing files
31+
32+
----ddeebbuugg,, --dd
33+
Show debug information
34+
35+
DDEEPPEENNDDEENNCCIIEESS
36+
aawwss--ccllii
37+
Download from <https://aws.amazon.com/cli/>
38+
39+
IISSSSUUEE TTRRAACCKKEERR
40+
Report issues at <https://github.com/lanalang/smallville>
41+
42+
AAUUTTHHOORRSS
43+
Lana Lang.
44+
45+
Version 0.1.0 August 2023 download(1)

0 commit comments

Comments
 (0)