Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/npalm/action-docs
Generate docs for GitHub actions
https://github.com/npalm/action-docs
cli documentation-generator github-actions github-reusable-workflows
Last synced: 2 days ago
JSON representation
Generate docs for GitHub actions
- Host: GitHub
- URL: https://github.com/npalm/action-docs
- Owner: npalm
- License: mit
- Created: 2021-02-20T17:50:59.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-04-22T10:30:56.000Z (9 months ago)
- Last Synced: 2024-04-22T11:26:16.800Z (9 months ago)
- Topics: cli, documentation-generator, github-actions, github-reusable-workflows
- Language: TypeScript
- Homepage:
- Size: 1.35 MB
- Stars: 51
- Watchers: 4
- Forks: 19
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
 [](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).