Github-Action: Generate Docs from Bash Scripts

Github Action to auto-generate Antora module with Asciicoc contents based on inline-docs from bash script. Inline-docs must comply to shdoc.

Github Badge Github Badge Github Badge

Inputs

No inputs specified

Outputs

A new Antora module in docs/modules/auto-generated-bash-docs folder with generated asciidoc contents. The action expects valid docs/antora.yml file.

Example usage

- name: Checkout code
  uses: actions/checkout@v3

- name: Generate docs from bash scripts
  uses: sebastian-sommerfeld-io/github-action-generate-docs@main

- name: Commit and push
  uses: EndBug/add-and-commit@v9
  with:
    author_name: your-name
    author_email: you@example.com
    message: "your commit message"
    add: docs/modules

Bash script docs

Make sure your bash script docs align with https://github.com/reconquest/shdoc.

#!/bin/bash
# @file libexample
# @brief A library that solves some common problems.
# @description
#     The project solves lots of problems:
#      * Some problem
#      * Some other problem

FOO="bar"

# @description My super function.
# Not thread-safe.
#
# @example
#    echo "test: $(say-hello World)"
#
# @arg $1 string A value to print
#
# @exitcode 0 If successful
# @exitcode 1 If an empty string passed
say-hello() {
  if [[ ! "$1" ]]; then
    return 1;
  fi

  echo "Hello $1"
}

Risks and Technical Debts

Scale for Probability and Impact: Low, Medium and High

# Title Description Probability Impact Response

1

-

-

-

-

-

Contact

Feel free to contact me via sebastian@sommerfeld.io or visit my website https://www.sommerfeld.io.