Generate documentation from Custom Actions and Reusable Workflows.
1.5K
Generate documentation from Custom Actions and Reusable Workflows.
The actdocs is a utility to generate documentation from GitHub Actions in Markdown format. It's identified Custom Actions or Reusable Workflows automatically, then formats appropriately.
Documentation is generated by the following command:
actdocs generate action.yml
For example, write the following Custom Actions and save it as action.yml.
name: Example Action
description: A example for Custom 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 "::set-output name=result::example"
Run actdocs generate action.yml, the following Markdown is output.
## 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.
Simply change the file you specify.
actdocs generate workflows.yml
The actdocs automatically switches its behavior for Reusable Workflows.
Download the latest compiled binaries and put it anywhere in your executable path.
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
If you have Go 1.18+ development environment:
git clone https://github.com/tmknom/actdocs
cd actdocs/
make install
actdocs --help
You can inject to existing file. Write the injection comments to Markdown.
<!-- actdocs start -->
<!-- actdocs end -->
Use inject command with --file or -f option.
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.
You can sort items by name and required.
Run actdocs with --sort or -s option.
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 onlyYou can format to json.
Run actdocs with --format option.
actdocs generate --format=json action.yml
Supported format is markdown and json.
The actdocs can be run as a container by mounting a directory such as the following command:
docker run --rm -v "$(pwd):/work" -w "/work" tmknom/actdocs generate action.yml
For full details, run actdocs --help.
Generate documentation from Custom 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
-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.
You can use the make command.
Build:
make build
Test:
make test
Lint:
make lint
For more information, run make help.
When create a pull request, the following workflows are executed automatically at GitHub Actions.
Run the following command to bump up.
make bump
This command will execute the following steps:
Then review and merge, so the release is ready to go.
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.
Finally, we can use the new version! :tada:
Use Dependabot version updates. For more information, see dependabot.yml.
Stored environment secrets for the following environments in this repository.
DOCKERHUB_TOKEN: Personal access token used to log against Docker Hub, and it's used by the releasing workflow.See Releases.
See tmknom/actdocs.
Apache 2 Licensed. See LICENSE for full details.
Content type
Image
Digest
sha256:85c5e7369…
Size
1.4 MB
Last updated
about 3 years ago
docker pull tmknom/actdocs