Skip to content

Commit 0106ec5

Browse files
DannyBenDannyBen
committed
update man and markdown templates and examples
1 parent 711194d commit 0106ec5

File tree

30 files changed

+365
-78
lines changed

30 files changed

+365
-78
lines changed

‎examples/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ Each of these examples demonstrates one aspect or feature of bashly.
6969
## Documentation generation
7070

7171
- [render-mandoc](render-mandoc#readme) - auto-generate man pages for your script
72+
- [render-markdown](render-markdown#readme) - auto-generate markdown documentation for your script
7273

7374
## Other examples
7475

‎examples/render-mandoc/README.md‎

Lines changed: 1 addition & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -53,54 +53,5 @@ flags:
5353
5454
## Generated script output
5555
56-
### `$ man docs/download.1 | col -bx`
57-
58-
```shell
59-
download(1) Sample application download(1)
60-
61-
NAME
62-
download - Sample application
63-
64-
SYNOPSIS
65-
download SOURCE [TARGET...] OPTIONS
66-
67-
DESCRIPTION
68-
Sample application
69-
70-
ARGUMENTS
71-
SOURCE
72-
Source to download from
73-
74-
• Required
75-
76-
• Allowed Values: server1, server2
77-
78-
TARGET
79-
Target filename (default: same as source)
80-
81-
• Repeatable
82-
83-
OPTIONS
84-
--force, -f
85-
Overwrite existing files
86-
87-
--debug, -d
88-
Show debug information
89-
90-
DEPENDENCIES
91-
aws-cli
92-
Download from <https://aws.amazon.com/cli/>
93-
94-
ISSUE TRACKER
95-
Report issues at <https://github.com/lanalang/smallville>
96-
97-
AUTHORS
98-
Lana Lang.
99-
100-
Version 0.1.0 August 2023 download(1)
101-
102-
103-
```
104-
105-
56+
*None*
10657

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

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,4 @@ Download from \<https://aws.amazon.com/cli/\>
6262

6363
# ISSUE TRACKER
6464

65-
66-
6765
Report issues at \<https://github.com/lanalang/smallville\>

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

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ version: 0.1.0
77
x_mandoc_authors: Lana Lang
88
x_mandoc_footer: |-
99
# ISSUE TRACKER
10-
1110
Report issues at <https://github.com/lanalang/smallville>
1211
1312
dependencies:

‎examples/render-markdown/README.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Render Markdown Example
2+
3+
This example shows how to render markdown documentation from your bashly
4+
commands, and how to use custom properties to add more information to
5+
the markdown output.
6+
7+
This example was generated with:
8+
9+
<!-- include: docs/index.md -->
10+
11+
```bash
12+
$ bashly init --minimal
13+
# ... now edit src/bashly.yml to match the example ...
14+
$ bashly render :markdown docs
15+
```
16+
17+
-----
18+
19+
## `bashly.yml`
20+
21+
```yaml
22+
name: download
23+
help: Sample application
24+
version: 0.1.0
25+
26+
# Optional, custom properties that are used by the markdown renderer
27+
# Run `bashly render :markdown --about` for more info.
28+
x_markdown_footer: |-
29+
# ISSUE TRACKER
30+
31+
Report issues at <https://github.com/lanalang/smallville>
32+
33+
dependencies:
34+
aws-cli: Download from <https://aws.amazon.com/cli/>
35+
36+
args:
37+
- name: source
38+
required: true
39+
allowed: [server1, server2]
40+
help: Source to download from
41+
- name: target
42+
help: "Target filename (default: same as source)"
43+
repeatable: true
44+
45+
flags:
46+
- long: --force
47+
short: -f
48+
help: Overwrite existing files
49+
- long: --debug
50+
short: -d
51+
help: Show debug information
52+
```
53+
54+
## `docs/index.md`
55+
56+
````markdown
57+
# download
58+
59+
Sample application
60+
61+
| Attributes | &nbsp;
62+
|------------------|-------------
63+
| Version: | 0.1.0
64+
65+
## Usage
66+
67+
```bash
68+
download SOURCE [TARGET...] [OPTIONS]
69+
```
70+
71+
## Dependencies
72+
73+
#### *aws-cli*
74+
75+
Download from \<https://aws.amazon.com/cli/\>
76+
77+
## Arguments
78+
79+
#### *SOURCE*
80+
81+
Source to download from
82+
83+
| Attributes | &nbsp;
84+
|-----------------|-------------
85+
| Required: | ✓ Yes
86+
| Allowed Values: | server1, server2
87+
88+
#### *TARGET*
89+
90+
Target filename (default: same as source)
91+
92+
| Attributes | &nbsp;
93+
|-----------------|-------------
94+
| Repeatable: | ✓ Yes
95+
96+
## Options
97+
98+
#### *--force, -f*
99+
100+
Overwrite existing files
101+
102+
#### *--debug, -d*
103+
104+
Show debug information
105+
106+
# ISSUE TRACKER
107+
108+
109+
110+
Report issues at \<https://github.com/lanalang/smallville\>
111+
112+
````
113+
114+
115+
## Generated script output
116+
117+
*None*
118+

‎examples/render-markdown/docs/index.md‎

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

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

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

‎examples/render-markdown/test.sh‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
#!/usr/bin/env bash
2+
3+
rm -f ./src/*.sh
4+
5+
set -x
6+
7+
bashly render :markdown docs
8+
9+
### Try Me ###
10+
11+
cat docs/index.md

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

Lines changed: 23 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,7 @@ will then use [pandoc](https://command-not-found.com/pandoc) to convert them.
1212
$ bashly render :mandoc docs
1313
```
1414

15-
## Special template features
16-
17-
### Preview
15+
## Viewing the output
1816

1917
Setting the environment variable `PREVIEW` to the full command you wish
2018
to preview, will prompt the renderer to show the output using the `man`
@@ -28,13 +26,27 @@ $ PREVIEW="cli download" bashly render :mandoc docs
2826
$ PREVIEW="cli download" bashly render :mandoc docs --watch
2927
```
3028

31-
### Footer
29+
In addition, you can use one of the following commands:
30+
31+
```bash
32+
# View the man page interactively
33+
$ man docs/cli-download.1
34+
35+
# Print the man page to stdout
36+
$ man docs/cli-download.1 | col -bx
37+
```
38+
39+
## Supported custom definitions
40+
41+
Add these definitions to your `bashly.yml` to render them in your
42+
markdown:
43+
44+
### Footer: `x_mandoc_footer`
3245

33-
You can add additional sections to any of the generated man pages, by
34-
adding a property named `x_mandoc_footer` to any of your commands in
35-
your `bashly.yml`.
46+
Add additional sections to your man pages. This field is expected
47+
to be in markdown format.
3648

37-
This field should contain a markdown string, for example:
49+
#### Example
3850

3951
```yaml
4052
x_mandoc_footer: |-
@@ -43,13 +55,11 @@ x_mandoc_footer: |-
4355
Report issues at <https://github.com/lanalang/smallville>
4456
```
4557
46-
### Authors
58+
### Authors: `x_mandoc_authors`
4759

48-
You can specify an authors string that will be added to the man page,
49-
by adding a property named `x_mandoc_authors` to any of your commands
50-
in your `bashly.yml`.
60+
Add an authors string to your man pages.
5161

52-
For example:
62+
#### Example
5363

5464
```yaml
5565
x_mandoc_authors: Lana Lang

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

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,31 @@ Render markdown documents for your script.
99
$ bashly render :markdown docs
1010
```
1111

12-
## Viewing your markdown documents
12+
## Viewing the output
1313

14-
In order to preview your markdown files, you can use the
14+
In order to view your markdown files, you can use
1515
[Madness markdown server](https://madness.dannyb.co/):
1616

1717
```bash
1818
$ gem install madness
1919
$ madness server docs
2020
```
21+
22+
## Supported custom definitions
23+
24+
Add these definitions to your `bashly.yml` to render them in your
25+
markdown:
26+
27+
### Footer: `x_markdown_footer`
28+
29+
Add additional sections to your man pages. This field is expected
30+
to be in markdown format.
31+
32+
#### Example
33+
34+
```yaml
35+
x_markdown_footer: |-
36+
# ISSUE TRACKER
37+
38+
Report issues at <https://github.com/lanalang/smallville>
39+
```

0 commit comments

Comments
 (0)