Skip to content

Commit f68192e

Browse files
mmichaelismmichaelis
authored
docs: Enhance Documentation (#21)
2 parents bc824e2 + 99ce819 commit f68192e

14 files changed

Lines changed: 621 additions & 121 deletions

‎.github/workflows/release-prepare.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,11 @@ jobs:
3838
echo "prev_version=$(cat .version)" >> $GITHUB_OUTPUT
3939
bin/version.sh ${{ github.event.inputs.release_type }}
4040
echo "next_version=$(cat .version)" >> $GITHUB_OUTPUT
41+
- name: Update Documentation
42+
id: update-docs
43+
run: |
44+
echo "Update documentation for version ${{ steps.version.outputs.next_version }}"
45+
bin/docs.sh
4146
- name: Create pull request
4247
id: create-pull-request
4348
# https://github.com/peter-evans/create-pull-request

‎README.md‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# lib-bash – Bash Libraries
22

3-
![Lib-Bash Decorative Image](img/LibBashGitHubSocialPreview.jpg)
3+
![Lib-Bash Decorative Image](docs/img/LibBashGitHubSocialPreview.jpg)
44

55
A set of libraries to use from within your Bash scripts.
66

@@ -51,6 +51,20 @@ ${COLOR_YELLOW}This is yellow text.${COLOR_RESET}
5151
EOF
5252
```
5353

54+
### lib_gnucompat
55+
56+
Utility functions and dynamically defined constants for scripts preferring
57+
(or requiring) GNU compatible tooling. Meant especially for systems such as
58+
MacOS, to prefer GNU-Tools like `coreutils` by preferring prefixed tools like
59+
`gsed`, `gawk`.
60+
61+
**Usage Examples**:
62+
63+
```bash
64+
echo "Hello, World!" | \
65+
"${SED}" --regexp-extended "s/World/GNU/g"
66+
```
67+
5468
### lib_init
5569

5670
Apply general recommended strictness settings for Bash scripts. Includes support

‎bin/doc-single.sh‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
#!/usr/bin/env bash
2+
###
3+
### Script to generate Markdown documentation for a single script.
4+
###
5+
### In contrast to more sophisticated approaches, this script just generates
6+
### the Markdown from lines starting with three hashes (###) and the following
7+
### line.
8+
###
9+
### Usage:
10+
###
11+
### ```bash
12+
### doc-single.sh <script> > <output>
13+
### ```
14+
###
15+
16+
set -o errexit # abort on nonzero exit status
17+
set -o nounset # abort on unbound variable
18+
set -o pipefail # don't hide errors within pipes
19+
20+
function main() {
21+
local script="${1?Missing script}"
22+
local line
23+
# Boolean flag, to signal, if the previous line was an empty documentation
24+
# line. This is used to prevent multiple empty lines in the output.
25+
local empty=0
26+
27+
while IFS= read -r line; do
28+
if [[ "${line}" =~ ^"###" ]]; then
29+
local content="${line:3}"
30+
# If first char is a space, remove it. Do nothing, especially if
31+
# the line is empty. Do not remove more than once space, as it might
32+
# be intentional.
33+
content="${content#"${content%%[![:space:]]*}"}"
34+
35+
if [[ -n "${content}" ]]; then
36+
# If the previous line was an empty line, print an empty line to
37+
# separate the sections.
38+
if ((empty == 1)); then
39+
echo
40+
fi
41+
empty=0
42+
echo "${content}"
43+
else
44+
# If the line is empty, set the empty flag to true.
45+
empty=1
46+
fi
47+
fi
48+
done <"${script}"
49+
}
50+
51+
main "${@}"

‎bin/docs.sh‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
#!/usr/bin/env bash
2+
###
3+
### Script to generate Markdown documentation for all library files.
4+
###
5+
### Invokes `doc-single.sh` for each library file `lib_*.sh`. The output is
6+
### written to `docs/lib`. Before processing each library file, the target
7+
### directory is cleared and ensures that it exists.
8+
###
9+
### Usage:
10+
###
11+
### ```bash
12+
### doc.sh
13+
### ```
14+
###
15+
16+
set -o errexit # abort on nonzero exit status
17+
set -o nounset # abort on unbound variable
18+
set -o pipefail # don't hide errors within pipes
19+
20+
MY_PATH="$(realpath "${BASH_SOURCE[0]}")"
21+
SCRIPT_DIR="$(dirname "${MY_PATH}")"
22+
readonly MY_PATH
23+
readonly SCRIPT_DIR
24+
readonly DOC_SINGLE="${SCRIPT_DIR}/doc-single.sh"
25+
readonly LIB_BASH_DIR="${SCRIPT_DIR}/.."
26+
readonly LIB_DOCS_DIR="${SCRIPT_DIR}/../docs/lib"
27+
28+
function main() {
29+
rm -rf "${LIB_DOCS_DIR}"
30+
mkdir -p "${LIB_DOCS_DIR}"
31+
32+
local lib
33+
34+
for lib in "${LIB_BASH_DIR}"/lib_*.sh; do
35+
local lib_name
36+
lib_name="$(basename "${lib}")"
37+
local target="${LIB_DOCS_DIR}/${lib_name%.sh}.md"
38+
"${DOC_SINGLE}" "${lib}" >"${target}"
39+
done
40+
}
41+
42+
main "${@}"

‎docs/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# lib-bash – Bash Libraries
2+
3+
![Lib-Bash Decorative Image](img/LibBashGitHubSocialPreview.jpg)
4+
5+
A set of libraries to use from within your Bash scripts.

img/LibBashGitHubSocialPreview.jpg renamed to docs/img/LibBashGitHubSocialPreview.jpg

File renamed without changes.

‎docs/lib/lib_console.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
2+
# lib_console.sh
3+
4+
Include for console support.
5+
6+
**Usage**:
7+
8+
```bash
9+
MY_PATH="$(realpath "${BASH_SOURCE[0]}")"
10+
SCRIPT_DIR="$(dirname "${MY_PATH}")"
11+
readonly MY_PATH
12+
readonly SCRIPT_DIR
13+
readonly LIB_BASH_DIR="${SCRIPT_DIR}/lib_bash"
14+
source "${LIB_BASH_DIR}/lib_console.sh"
15+
```
16+
17+
## Color Constants
18+
19+
### Foreground Colors
20+
21+
* `COLOR_RESET`: Reset the color.
22+
* `COLOR_BLACK`: Black color.
23+
* `COLOR_RED`: Red color.
24+
* `COLOR_GREEN`: Green color.
25+
* `COLOR_YELLOW`: Yellow color.
26+
* `COLOR_BLUE`: Blue color.
27+
* `COLOR_MAGENTA`: Magenta color.
28+
* `COLOR_CYAN`: Cyan color.
29+
* `COLOR_WHITE`: White color.
30+
* `COLOR_GRAY`: Gray color.
31+
* `COLOR_LIGHT_RED`: Light red color.
32+
* `COLOR_LIGHT_GREEN`: Light green color.
33+
* `COLOR_LIGHT_YELLOW`: Light yellow color.
34+
* `COLOR_LIGHT_BLUE`: Light blue color.
35+
* `COLOR_LIGHT_MAGENTA`: Light magenta color.
36+
* `COLOR_LIGHT_CYAN`: Light cyan color.
37+
* `COLOR_LIGHT_WHITE`: Light white color.
38+
39+
### Background Colors
40+
41+
* `COLOR_BG_BLACK`: Black background color.
42+
* `COLOR_BG_RED`: Red background color.
43+
* `COLOR_BG_GREEN`: Green background color.
44+
* `COLOR_BG_YELLOW`: Yellow background color.
45+
* `COLOR_BG_BLUE`: Blue background color.
46+
* `COLOR_BG_MAGENTA`: Magenta background color.
47+
* `COLOR_BG_CYAN`: Cyan background color.
48+
* `COLOR_BG_WHITE`: White background color.
49+
50+
## Logging
51+
52+
All logging functions to output information to STDERR. STDERR is preferred,
53+
as it is not affected by the output redirection of the script, thus, the
54+
desired standard output can be redirected to a file or another command.
55+
56+
### log_debug
57+
58+
Output debug message.
59+
60+
The function is used to output debug information. It is only printed
61+
if the `DEBUG` variable is set to a value greater than 0 (zero).
62+
63+
If the standard output supports color, the debug information is printed in
64+
gray color. Otherwise, the debug information is printed without color.
65+
66+
**Usage**:
67+
68+
```bash
69+
log_debug "Only show if DEBUG=1 (or more)"
70+
grep "pattern" file.txt | log_debug
71+
```
72+
73+
### log_info
74+
75+
Output information message.
76+
77+
The function is used to output information messages. No extra color is
78+
used for the information message.
79+
80+
**Usage**:
81+
82+
```bash
83+
log_info "An informational message."
84+
grep "pattern" file.txt | log_info
85+
```
86+
87+
### log_warn
88+
89+
Output warning message.
90+
91+
The function is used to output warning messages. The warning message
92+
is printed in yellow color.
93+
94+
**Usage**:
95+
96+
```bash
97+
log_warn "A warning notice."
98+
grep "pattern" file.txt | log_warn
99+
```
100+
101+
### log_error
102+
103+
Output error message.
104+
105+
The function is used to output error messages. The error message is
106+
printed in red color.
107+
108+
**Usage**:
109+
110+
```bash
111+
log_error "An error."
112+
grep "pattern" file.txt | log_error
113+
```
114+
115+
### log_fatal
116+
117+
Output a fatal error message.
118+
119+
The function is used to output error messages. The error message is
120+
printed with dark red background and bright yellow color.
121+
122+
**Usage**:
123+
124+
```bash
125+
log_fatal "A fatal error."
126+
grep "pattern" file.txt | log_fatal
127+
```
128+
129+
### ccat
130+
131+
Alternative to `cat` that also processes colored input.
132+
133+
**Usage**:
134+
135+
```bash
136+
ccat <<EOF
137+
${COLOR_RED}This is red text.${COLOR_RESET}
138+
${COLOR_YELLOW}This is yellow text.${COLOR_RESET}
139+
EOF
140+
```

‎docs/lib/lib_gnucompat.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
2+
# GNU-Tools Compatibility Layer
3+
4+
This script provides compatibility functions for GNU tools on non-GNU
5+
systems, such as macOS.
6+
7+
**Usage**:
8+
9+
```bash
10+
MY_PATH="$(realpath "${BASH_SOURCE[0]}")"
11+
SCRIPT_DIR="$(dirname "${MY_PATH}")"
12+
readonly MY_PATH
13+
readonly SCRIPT_DIR
14+
readonly LIB_BASH_DIR="${SCRIPT_DIR}/lib_bash"
15+
source "${LIB_BASH_DIR}/lib_gnucompat.sh"
16+
```
17+
18+
## Tools Aliases
19+
20+
These functions will return the corresponding GNU-tool on non-GNU systems,
21+
if available. Such as `gsed` on macOS, which is the GNU version of `sed`.
22+
23+
* `SED`: GNU `sed` command
24+
* `AWK`: GNU `awk` command
25+
* `GREP`: GNU `grep` command
26+
* `FIND`: GNU `find` command
27+
* `SORT`: GNU `sort` command
28+
* `TAR`: GNU `tar` command
29+
* `DATE`: GNU `date` command
30+
* `XARGS`: GNU `xargs` command
31+
* `CUT`: GNU `cut` command
32+
* `HEAD`: GNU `head` command
33+
* `TAIL`: GNU `tail` command
34+
* `TR`: GNU `tr` command
35+
* `UNIQ`: GNU `uniq` command
36+
* `WC`: GNU `wc` command
37+
* `DIFF`: GNU `diff` command
38+
39+
## Functions
40+
41+
### is_gnu
42+
43+
Signal, if the given tool is a GNU tool.
44+
45+
**Usage**:
46+
47+
```bash
48+
if ! is_gnu "sed"; then
49+
echo "Not a GNU tool."
50+
fi
51+
```

‎docs/lib/lib_init.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
2+
# lib_init.sh
3+
4+
A file for some initial Bash Scripting best practices. It applies the
5+
following settings:
6+
7+
* `errexit`: Abort on nonzero exit status
8+
* `nounset`: Abort on unbound variable
9+
* `pipefail`: Don't hide errors within pipes
10+
* `xtrace`: Show expanded commands if `DEBUG` is set to 2. Set to 1 for
11+
more verbose output.
12+
13+
**Usage**:
14+
15+
```bash
16+
MY_PATH="$(realpath "${BASH_SOURCE[0]}")"
17+
SCRIPT_DIR="$(dirname "${MY_PATH}")"
18+
readonly MY_PATH
19+
readonly SCRIPT_DIR
20+
readonly LIB_BASH_DIR="${SCRIPT_DIR}/lib_bash"
21+
source "${LIB_BASH_DIR}/lib_init.sh"
22+
```
23+
24+
## Constants
25+
26+
* `DEBUG`: Provide option to trigger debug output with different verbosity
27+
levels.
28+
Call with `DEBUG=2 <command>.sh <file>` to enable verbose debug output

‎docs/lib/lib_scriptinfo.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
2+
# lib_scriptinfo.sh
3+
4+
Include for script information functions.
5+
6+
**Usage**:
7+
8+
```bash
9+
MY_PATH="$(realpath "${BASH_SOURCE[0]}")"
10+
SCRIPT_DIR="$(dirname "${MY_PATH}")"
11+
readonly MY_PATH
12+
readonly SCRIPT_DIR
13+
readonly LIB_BASH_DIR="${SCRIPT_DIR}/lib_bash"
14+
source "${LIB_BASH_DIR}/lib_scriptinfo.sh"
15+
```
16+
17+
## Functions
18+
19+
### get_script_name
20+
21+
Get script name (without path, with extension).
22+
23+
* **Arguments**: _None_
24+
* **Returns**: The script name.

0 commit comments

Comments
 (0)