actdocs

Generate documentation from Actions and Reusable Workflows.

Description

The actdocs is a utility to generate documentation from GitHub Actions in Markdown format. It's identified Actions or Reusable Workflows automatically, then formats appropriately.

Getting Started

Documentation is generated by the following command:

docker run --rm -v "$(pwd):/work" -w "/work" \
ghcr.io/tmknom/actdocs generate action.yml

Actions

For example, write the following Actions and save it as action.yml.

name: Example Action
description: A example for Actions.
inputs:
  hello:
    default: "Hello, world."
    required: false
    description: "A input value."
  answer:
    default: 42
    required: true
    description: "Answer to the Ultimate Question of Life, the Universe, and Everything."
outputs:
  result:
    value: ${{ steps.main.outputs.result }}
    description: "A output value."
runs:
  using: composite
  steps:
    - id: main
      shell: bash
      run: echo "result=example" >> "${GITHUB_OUTPUT}"

Run actdocs generate action.yml, the following Markdown is output.

## Description

A example for Actions.

## Inputs

| Name | Description | Default | Required |
| :--- | :---------- | :------ | :------: |
| hello | A input value. | `Hello, world.` | no |
| answer | Answer to the Ultimate Question of Life, the Universe, and Everything. | `42` | yes |

## Outputs

| Name | Description |
| :--- | :---------- |
| result | A output value. |

These outputs can be sorted or injected into a specified file. For more information, see Usage.

Reusable Workflows

Simply change the file you specify.

docker run --rm -v "$(pwd):/work" -w "/work" \
ghcr.io/tmknom/actdocs generate .github/workflows/lint.yml

The actdocs automatically switches its behavior for Reusable Workflows.

Installation

Pull Docker image

You can pull from Docker Hub or GitHub Packages, whichever you prefer.

Docker Hub:

docker pull tmknom/actdocs

GitHub Packages:

docker pull ghcr.io/tmknom/actdocs

Download binary

Download the latest compiled binaries and put it anywhere in your executable path.

• GitHub Releases

Build from source code

If you have Go 1.18+ development environment:

git clone https://github.com/tmknom/actdocs
cd actdocs/
make install
actdocs --help

Usage

Injection

You can inject to existing file. Write the injection comments to Markdown.

<!-- actdocs start -->
<!-- actdocs end -->

Use inject command with --file or -f option.

docker run --rm -v "$(pwd):/work" -w "/work" \
ghcr.io/tmknom/actdocs inject --file README.md action.yml

Then, output is injected to the specified file.

Note

inject command can be used with --dry-run option to check the behavior without overwriting the file.

Sort

You can sort items by name and required. Run actdocs with --sort or -s option.

docker run --rm -v "$(pwd):/work" -w "/work" \
ghcr.io/tmknom/actdocs generate --sort action.yml

Of course, it can be used in combination with inject command.

If you prefer to sort in another way, try the following options:

• --sort-by-name: sort by name only
• --sort-by-required: sort by required only

Format

You can format to json. Run actdocs with --format option.

docker run --rm -v "$(pwd):/work" -w "/work" \
ghcr.io/tmknom/actdocs generate --format=json action.yml

Supported format is markdown and json.

Show help

For full details, run docker run --rm ghcr.io/tmknom/actdocs --help.

Generate documentation from Actions and Reusable Workflows

Usage:
  actdocs [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  generate    Generate documentation
  help        Help about any command
  inject      Inject generated documentation to existing file

Flags:
      --debug              show debugging output
      --format string      output format [markdown json] (default "markdown")
  -h, --help               help for actdocs
      --omit               omit for markdown if item not exists
  -s, --sort               sort items by name and required
      --sort-by-name       sort items by name
      --sort-by-required   sort items by required
  -v, --version            version for actdocs

Use "actdocs [command] --help" for more information about a command.

Maintainer Guide

make build

make test

make lint

make bump

make release

Changelog

See Releases.

Source Repository

See tmknom/actdocs.

License

Apache 2 Licensed. See LICENSE for full details.