Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pndurette/gh-actions-auto-docs
A GitHub Action for generating GitHub Action Markdown documentation
https://github.com/pndurette/gh-actions-auto-docs
auto-docs auto-documentation documentation-generator github-actions
Last synced: 3 months ago
JSON representation
A GitHub Action for generating GitHub Action Markdown documentation
- Host: GitHub
- URL: https://github.com/pndurette/gh-actions-auto-docs
- Owner: pndurette
- License: mit
- Created: 2023-02-21T03:05:45.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-03-18T22:46:36.000Z (10 months ago)
- Last Synced: 2024-10-14T09:13:03.366Z (3 months ago)
- Topics: auto-docs, auto-documentation, documentation-generator, github-actions
- Language: Python
- Homepage:
- Size: 29.3 KB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# gh-actions-auto-docs
> A GitHub Action for generating GitHub Action documentation—[including its own!](.github/workflows/doc.yml)
[](https://github.com/pndurette/gh-actions-auto-docs/actions/workflows/test.yml)
## Features
* Generates GitHub Action documentation from the `action.yml` file
* Support multi-line Markdown `description` yaml fields—only document your action once! (see [Example](#example))
* Features git auto-commit to open PRs or push to branches
## Setup
1. In your `README.md` (or anywhere you'd like), add the template markers where you want the documentation to be inserted:
```markdown
```
2. Add `pndurette/gh-actions-auto-docs` to a workflow, for example:
*(Note the requirements for allowing the workflow to push to git!)*
```yaml
name: Generate Action Docs
on: [pull_request]
jobs:
doc:
runs-on: ubuntu-latest
permissions:
# Required to push changes!
contents: write
steps:
- uses: actions/checkout@v3
with:
# Required to push changes!
ref: ${{ github.event.pull_request.head.ref }}
- uses: pndurette/gh-actions-auto-docs@v1
```
## Configuration
*This section was automatically generated by this action from its own [`action.yml`](./action.yml)*
### Inputs
|Input|Description|Default|Required|
|-----|-----------|-------|:------:|
|`action_yaml_file`|The path to the GitHub Action's `action.yml` file|`./action.yml`|no|
|`include_inputs`|Whenever to document the action's inputs|`true`|no|
|`include_outputs`|Whenever to document the action's outputs|`true`|no|
|`heading_size`|
The Markdown heading size to use for the documented
sections (i.e. number of #)
|`3`|no|
|`template_file`|The file used as template|`./README.md`|no|
|`target_file`|The resulting file of the template substitution.
To update in-place, this can be the same as template_file.
|`./README.md`|no|
|`marker_start`|The opening marker from which the template substitution
will take place
|``|no|
|`marker_end`|The closing marker to which the template substitution
will take place
|``|no|
|`git_push`|Whenever to commit and push changes changes to `target_file`|`true`|no|
|`git_push_user_name`|The git user name to commit with|`github-actions[bot]`|no|
|`git_push_user_email`|The git user email to commit with|`github-actions[bot]@users.noreply.github.com`|no|
|`git_commit_message`|The git commit message|`GitHub Action Auto-Docs`|no|
|`git_commit_signoff`|Whenever to sign-off the git commit|`false`|no|
## Example
This `action.yml` ...
```yaml
# [...]
inputs:
param1:
description: This param has some **bold** and *italics*
required: true
default: value1
param2:
description: |
Path to some yaml:
\```yaml
foo: bar
baz:
- abc
\```
:warning: **Some cautionnary `tale`!**
required: false
default: ./some_file.yaml
param3:
description: See [link to somewhere](https://github.com)
outputs:
output1:
description: |
A list to consider:
1. This
2. That
output2:
description: |
Someone once said:
> Hello, how do you do?
output3:
description: This is it
# [...]
```
... Would generate to:
### Inputs
|Input|Description|Default|Required|
|-----|-----------|-------|:------:|
|`param1`|
Path to some yaml:
foo: bar
baz:
- abc
:warning: Some cautionnary tale!
|`./some_file.yaml`|no|
|`param2`|This param has some **bold** and *italics*|`value1`|yes|
|`param3`|See [link to somewhere](https://github.com)|n/a|no|
### Outputs
|Output|Description|
|------|-----------|
|`output1`|A list to consider:
1. This
2. That
|
|`output2`|Someone once said:
Hello, how do you do?
|
|`output3`|This is it|
## Licence
[The MIT License (MIT)](LICENSE) Copyright © 2023-2024 Pierre Nicolas Durette