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

Click to see details

Requirements

• GNU Make
• Docker
• GitHub CLI

Development

You can use the make command.

Build:

make build

Test:

make test

Lint:

make lint

For more information, run make help.

CI

When create a pull request, the following workflows are executed automatically at GitHub Actions.

• Test
• Lint Go
• Lint Markdown
• Lint YAML
• Lint Action
• Lint Shell

Release

1. Bump up to a new version

Run the following command to bump up.

make bump

This command will execute the following steps:

1. Update VERSION
2. Commit, push, and create a pull request
3. Open the web browser automatically for reviewing pull request

Then review and merge, so the release is ready to go.

2. Publish the new version

Run the following command to publish a new tag at GitHub.

make release

Then releasing workflow with GoReleaser is run automatically at GitHub Actions that executes the following steps.

1. Build executable binaries for Linux, Windows and Darwin
2. Create a new GitHub Release, and publish binaries
3. Push Docker images to Docker Hub and GitHub Packages

Finally, we can use the new version! 🎉

Administration

Package management

• Binaries
  • GitHub Releases
• Docker images
  • Docker Hub
  • GitHub Packages

Dependency management

Use Dependabot version updates. For more information, see dependabot.yml.

Secrets management

Stored environment secrets for the following environments in this repository.

• release
  • DOCKERHUB_TOKEN: Personal access token used to log against Docker Hub, and it's used by the releasing workflow.

Changelog

See Releases.

Source Repository

See tmknom/actdocs.