makeshift / auto-doc

:octocat: Github action/CLI to convert your GitHub actions.yml to markdown.

auto-doc

Generate documentation for your actions.(yml|yaml).

Table of Contents

• Usage
• Inputs
• Examples
• CLI
  • Installation
  • Synopsis
  • Options
• Credits
• Report Bugs

Usage

Add the Inputs and/or Outputs H2 header to any markdown file.

...
    steps:
      - uses: actions/checkout@v2
      - name: Run auto-doc
        uses: tj-actions/[email protected]

Inputs

INPUT	TYPE	REQUIRED	DEFAULT	DESCRIPTION
action	string	false	"action.yml"	Path to the action.yml file
bin_path	string	false		Path to the auto-doc binary
col_max_width	string	false	"1000"	Max width of a column
col_max_words	string	false	"6"	Max number of words per line in a column
input_columns	string	false		List of Input columns names to display, default (display all columns)
output	string	false	"README.md"	Path to the output file
output_columns	string	false		List of Output column names to display, default (display all columns)

👆 This is generated 👆 using 👉 action.yml

Examples

Create a pull request each time the action.yml inputs/outputs change

name: Update README.md with the latest actions.yml

on:
  push:
    branches:
      - main

jobs:
  update-doc:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/[email protected]
         with:
           fetch-depth: 0  # otherwise, you will failed to push refs to dest repo

       - name: Run auto-doc
         uses: tj-actions/[email protected]

       - name: Verify Changed files
         uses: tj-actions/[email protected]
         id: verify-changed-files
         with:
           files: |
             README.md

       - name: Create Pull Request
         if: steps.verify-changed-files.outputs.files_changed == 'true'
         uses: peter-evans/create-pull-request@v3
         with:
           base: "main"
           title: "auto-doc: Updated README.md"
           branch: "chore/auto-doc-update-readme"
           commit-message: "auto-doc: Updated README.md"
           body: "auto-doc: Updated README.md"

CLI

Installation

Run

go install github.com/tj-actions/auto-doc@latest

Synopsis

Auto generate documentation for your github action.

auto-doc [flags]

Options

      --action string               action config file (default "action.yml")
      --colMaxWidth string          Max width of a column (default "1000")
      --colMaxWords string          Max number of words per line in a column (default "5")
  -h, --help                        help for auto-doc
      --inputColumns stringArray    list of input column names (default [Input,Type,Required,Default,Description])
      --output string               Output file (default "README.md")
      --outputColumns stringArray   list of output column names (default [Output,Type,Description])

• Free software: Apache License 2.0

If you feel generous and want to show some extra appreciation:

Credits

This package was created with Cookiecutter using cookiecutter-action

• cobra
• gobinaries
• goreleaser

Report Bugs

Report bugs at https://github.com/tj-actions/auto-doc/issues.

If you are reporting a bug, please include:

• Your operating system name and version.
• Any details about your workflow that might be helpful in troubleshooting.
• Detailed steps to reproduce the bug.