gha-docs

What is it?

A program to generate documentation for GitHub composite actions.

Installation

Stable Release Binaries

Substitute darwin for linux if installing on MacOS.

export GHA_DOCS_VERSION=v0.15.1
export GHA_DOCS_OS=linux
export GHA_DOCS_ARCH=amd64

curl -Lo ./gha-docs.tar.gz https://github.com/matty-rose/gha-docs/releases/download/$GHA_DOCS_VERSION/gha-docs-$GHA_DOCS_VERSION-$GHA_DOCS_OS-$GHA_DOCS_ARCH.tar.gz
tar -xzf gha-docs.tar.gz
chmod +x gha-docs && mv gha-docs /usr/local/bin

From Source

Go 1.17+ is required.

go install github.com/matty-rose/[email protected]

Usage

Run gha-docs to display general usage.

To output to stdout:

gha-docs generate path/to/action.yaml

Generating a README

This will overwrite any existing content in README.md.

gha-docs generate --output-file README.md path/to/action.yaml

To inject generated documentation into an existing file, adding the following markers in the file will cause the documentation to be generated between them, overwriting any content already existing between the markers, and preserving any content outside the markers.

<!-- BEGIN GHA DOCS -->
<!-- END GHA DOCS -->

Then use the -i/--inject flag to inject the documentation into the file specified by -o/--output-file e.g.

gha-docs generate -i -o README.md path/to/action.yaml

Future Improvements

• Add CI workflow to auto-commit find/replace version updates to README on release
• Parse config from .gha-docs.yml

License

MIT License - Copyright (c) 2021