pndurette / gh-actions-auto-docs

A GitHub Action for generating GitHub Action Markdown documentation

gh-actions-auto-docs

A GitHub Action for generating GitHub Action documentation—including its own!

Features

• Generates GitHub Action documentation from the action.yml file
• Support multi-line Markdown description yaml fields—only document your action once! (see 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:

<!--doc_begin-->
<!--doc_end-->

2. Add pndurette/gh-actions-auto-docs to a workflow, for example: (Note the requirements for allowing the workflow to push to git!)

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

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	<!--doc_begin-->	no
marker_end	The closing marker to which the template substitution will take place	<!--doc_end-->	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 ...

# [...]

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 ⚠️ Some cautionnary tale!	./some_file.yaml	no
param2	This param has some bold and italics	value1	yes
param3	See link to somewhere	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) Copyright © 2023-2024 Pierre Nicolas Durette