[](https://npmjs.org/package/action-docs) [](https://sonarcloud.io/dashboard?id=action-docs) [](https://sonarcloud.io/dashboard?id=action-docs) [](https://codescene.io/projects/49602) # 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 [action-docs-action](https://github.com/npalm/action-docs-action). ## TL;DR ### Add the following comment blocks to your README.md ```md # applicable for actions only # applicable for actions only ``` Optionally you can also add the following section to generate a usage guide, replacing \ and \ with the name and version of your project you would like to appear in your usage guide. ```md ``` ### Generate docs via CLI ```bash npm install -g action-docs cd # write docs to console action-docs # update README action-docs --update-readme ``` ### Run the cli ``` 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 `action-docs -u`. ```md ``` Or to include all of the above, use: ```md ``` For updating other Markdown files add the name of the file to the command `action-docs -u `. 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 `action-docs -s another/action.yml` ### Examples #### Print action markdown docs to console ```bash action-docs ``` #### Update README.md ```bash action-docs --update-readme ``` #### Print action markdown for non default action file ```bash action-docs --source another/action.yaml ``` #### Update readme, custom action file and set TOC level 3, custom readme ```bash action-docs --source ./some-dir/action.yml --toc-level 3 --update-readme docs.md ``` ## API ```javascript import { generateActionMarkdownDocs } from 'action-docs' await generateActionMarkdownDocs({ sourceFile: 'action.yml' tocLevel: 2 updateReadme: true readmeFile: 'README.md' }); ``` ## Contribution We welcome contributions, please checkout the [contribution guide](CONTRIBUTING.md). ## License This project is released under the [MIT License](./LICENSE).