Action docs

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

TL;DR

Add the following comment blocks to your README.md

1<!-- ya-action-docs-header source="action.yml" -->
2
3<!-- ya-action-docs-description source="action.yml" --> # applicable for actions only
4
5<!-- ya-action-docs-inputs source="action.yml" -->
6
7<!-- ya-action-docs-outputs source="action.yml" -->
8
9<!-- ya-action-docs-runs source="action.yml" --> # applicable for actions only

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.

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

Generate docs via CLI

1npm install -g ya-action-docs
2cd <your github action>
3
4# write docs to console
5ya-action-docs
6
7# update README
8ya-action-docs --update-readme

Run the cli

ya-action-docs -u

CLI

Options

The following options are available via the CLI

Options:
      --version              Show version number                       [boolean]
  -t, --toc-level            TOC level used for markdown   [number] [default: 2]
  -a, --action               GitHub action file
             [deprecated: use "source" instead] [string] [default: "action.yml"]
  -s, --source               GitHub source 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"]
  -n, --include-name-header  Include a header with the action/workflow name
                                                                       [boolean]
      --help                 Show help                                 [boolean]

Update the README

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

1<!-- ya-action-docs-header source="action.yml" -->
2
3<!-- ya-action-docs-description source="action.yml" -->
4
5<!-- ya-action-docs-inputs source="action.yml" -->
6
7<!-- ya-action-docs-outputs source="action.yml" -->
8
9<!-- ya-action-docs-runs action="action.yml" -->
10
11<!-- ya-action-docs-usage action="action.yml" project="<project>" version="<version>" -->

Or to include all of the above, use:

1<!-- ya-action-docs-all source="action.yml" project="<project>" version="<version>" -->

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

If you need to use another/action.yml:

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

Examples

Print action markdown docs to console

1ya-action-docs

Update README.md

1ya-action-docs --update-readme

Print action markdown for non default action file

1ya-action-docs --source another/action.yaml

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

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

API

1import { generateActionMarkdownDocs } from 'ya-action-docs'
2
3await generateActionMarkdownDocs({
4  sourceFile: 'action.yml'
5  tocLevel: 2
6  updateReadme: true
7  readmeFile: 'README.md'
8});

Contribution

We welcome contributions, please checkout the contribution guide.

License

This project is released under the MIT License.