action-docs

Action docs

A CLI to generate and update documentation for GitHub actions, based on the action definition .yml. To update your README in a GitHub workflow you can use the action-docs-action.

TL;DR

Add the following comment blocks to your README.md

<!-- action-docs-description action="action.yml" -->

<!-- action-docs-inputs action="action.yml" -->

<!-- action-docs-outputs action="action.yml" -->

<!-- action-docs-runs action="action.yml" -->

Optionally you can also add the following section to generate a usage guide, replacing <project> and <version> with the name and version of your project you would like to appear in your usage guide.

<!-- action-docs-usage action="action.yml" project="<project>" version="<version>" -->

Generate docs via CLI

npm install -g action-docs
cd <your github action>

# write docs to console
action-docs

# update reamde
action-docs --update-readme

Run the cli

action-docs -u

CLI

Options

The following options are available via the CLI

Options:
      --help           Show help                                       [boolean]
      --version        Show version number                             [boolean]
  -t, --toc-level      TOC level used for markdown         [number] [default: 2]
  -a, --action         GitHub action file       [string] [default: "action.yml"]
      --no-banner      Print no banner
  -u, --update-readme  Update readme file.                              [string]
  -l, --line-breaks    Used line breaks in the generated docs.
                          [string] [choices: "CR", "LF", "CRLF"] [default: "LF"]

Update the README

Action-docs can update your README based on the action.yml. The following sections can be updated: description, inputs, outputs and runs. Add the following tags to your README and run action-docs -u.

<!-- action-docs-description action="action.yml" -->

<!-- action-docs-inputs action="action.yml" -->

<!-- action-docs-outputs action="action.yml" -->

<!-- action-docs-runs action="action.yml" -->

For updating other Markdown files add the name of the file to the command action-docs -u <file>.

If you need to use another/action.yml:

1. write it in tags like action="another/action.yml";
2. specify in a command via the -a option like action-docs -a another/action.yml

Examples

Print action markdown docs to console

action-docs

Update README.md

action-docs --update-readme

Print action markdown for non default action file

action-docs --action another/action.yaml

Update readme, custom action file and set TOC level 3, custom readme

action-docs --action ./some-dir/action.yml --toc-level 3 --update-readme docs.md

API

import { generateActionMarkdownDocs } from 'action-docs'

await generateActionMarkdownDocs({
  actionFile: 'action.yml'
  tocLevel: 2
  updateReadme: true
  readmeFile: 'README.md'
});

Contribution

We welcome contributions, please checkout the contribution guide.

License

This project is released under the MIT License.

Changelog

2.0.0 (2024-02-04)

⚠ BREAKING CHANGES

• support multiple actions in a single readme (#505)

Features

• support multiple actions in a single readme (#505) (284bf3f)

Miscellaneous

• dependencies and refactor ci (#506) (44af6c0)
• deps: bump yargs from 17.7.1 to 17.7.2 (4fe7873)
• fix release build (f75d0c3)