Generate clean, self-contained usage help for Bash scripts from structured comments.
This tool extracts Doxygen-style comments from a .src.bash file,
converts them into Markdown, and injects the rendered help directly into
a minified .bash script.
The result is a compact, production-ready script that still provides rich, readable usage help at runtime.
# Create a source script
cat > example.src.bash <<'EOF'
#!/usr/bin/env bash
## @file example.src.bash
## @brief Example CLI tool
## @details
## Demonstrates usage help generation.
##
while getopts "h" option ; do
case "$option" in
h) usage_help ; exit 0 ;; ##- display usage help
esac
done
printf 'Hello, world\n'
EOF
# Run the tool
bash_usage_help_generator.bash example.src.bash
# Run the generated script
./example.bash -h
git clone https://github.com/wesley-dean/bash_usage_help_generator.git
cd bash_usage_help_generator
chmod +x bash_usage_help_generator.bash
# Optional
cp bash_usage_help_generator.bash ~/bin/
Usage:
bash_usage_help_generator.bash /path/to/script.src.bash
Assumes the image:
wesleydean/bash_usage_help_generator:latest
docker run --rm \
-v "$PWD:/work" \
wesleydean/bash_usage_help_generator:latest \
/work/example.src.bash
cat example.src.bash | \
docker run --rm -i \
wesleydean/bash_usage_help_generator:latest \
- > example.bash
The tool parses Doxygen-style comments that begin with ##.
@file → top-level title@fn → function title@brief → short description@details → longer description@param → grouped under "Parameters"@retval → grouped under "Return values"@return → grouped under "Returns"@par → section header@code / @endcode → fenced code block##- → inline option descriptions## @fn example()
## @brief Example function
## @param name the name to use
## @retval 0 success
## @retval 1 failure
h) usage_help ;; ##- display usage help
'--help') usage_help ;; ##- display usage help
Produces:
## Options
* `-h`: display usage help
* `--help`: display usage help
example.src.bash#!/usr/bin/env bash
## @file example.src.bash
## @brief Example CLI tool
## @details
## This script demonstrates usage help generation.
##
while getopts "h" option ; do
case "$option" in
h) usage_help ; exit 0 ;; ##- display usage help
esac
done
printf 'Hello\n'
bash_usage_help_generator.bash example.src.bash
example.bash (excerpt)usage_help() {
cat <<'__BASHLIB_USAGE_HELP__'
## Usage
`example.src.bash` [-h]
# file example.src.bash
## Brief
Example CLI tool
## Details
This script demonstrates usage help generation.
## Options
* `-h`: display usage help
__BASHLIB_USAGE_HELP__
}
./example.bash -h
awkBash-minifierusage_help() functionbuild/*.bash (intermediate)./script.bash (final)Run the full test suite with:
make test
This project uses:
Content type
Image
Digest
sha256:61be163c7…
Size
7.9 MB
Last updated
5 months ago
docker pull wesleydean/bash_usage_help_generator