Docs Generation

When searching for actual projects of CLI tools generating docs from comments in .sh files, shdoc is often in the short-list for a good reason.

Sh:erpa implements it via the sherpa doc or s d commands.

shdoc

The most part of your docs annotations, will often be in the beginning of your file. This can go directly into src/bin.sh as we are often there, of in a partial rendering above it like src/_globals.sh.

# @file Title of the Docs File (e.g. `myScript`)
# @brief The tagline just below it.
# @description
#     Content listed after the ## Overview tilte
#
#   This BasBox is doing:
#      * a
#      * b
#      * c
#      * etc

As all the files in the src/ will be merged into a single one on each build command, the header part should obviously be featured once.

Above each bash function, you can add that type of block:

# @description My super function.
# Not thread-safe.
#
# @example
#    echo "test: $(say-hello World)"
#
#
# @option -h | --help Display help.
# @option -v<value> | --value=<value> Set a value.
#
# @arg $1 string A value to print
#
# @stdout Output 'Hello $1'.
#   It hopes you say Hello back.
# @stderr Output 'Oups !' on error.
#   It did it again.
#
# @exitcode 0 If successful.
# @exitcode 1 If an empty string passed.
#
# @see validate()
# @see [shdoc](https://github.com/reconquest/shdoc).
say-hello() {
    if [[ ! "$1" ]]; then
        echo "Oups !" >&2
        return 1;
    fi

    echo "Hello $1"
}

What next?

As of now it's already a good enough start, and we'll see along the way how it feels, but already cheers to the people behind those projects.