auto-doc

GitHub Action generates a beautiful, easy-to-read markdown table or YAML code block with just a few lines of code. Say goodbye to manual table creation or outdated YAML code blocks and hello to streamlined documentation that is always up-to-date.

Features

Document your custom Github action using the action.yml file.
Document reusable workflows by specifying the filename.
Easy to understand markdown table of all inputs, outputs, and secrets.
Optional YAML code block for your action.yml file which includes all inputs.
Show deprecated inputs.
Fast and always up-to-date documentation.

Usage

Add any of the supported headings as a H2 header in any location of your markdown file.

Supported Headings

Inputs
Outputs
Secrets (only supported by reusable workflows)
Description (only supported by actions)

Example

Add one or more headings to your README.md

Note

This can be multiple headings supported by the input file

## Inputs

2. Update your workflow

...
    steps:
      - uses: actions/checkout@v4
      - name: Run auto-doc
        uses: tj-actions/auto-doc@v3

👇 This was generated 👇 using 👉: action.yml

Inputs

- uses: tj-actions/auto-doc@v3
  id: auto-doc
  with:
    # Optionally pass a path to 
    # the auto-doc binary 
    # Type: string
    bin_path: ''

    # Max width of a column
    # Type: string
    # Default: "1000"
    col_max_width: ''

    # Max number of words per 
    # line in a column 
    # Type: string
    # Default: "5"
    col_max_words: ''

    # Path to the yaml file
    # Type: string
    # Default: "action.yml"
    filename: ''

    # List of action.yml **input** columns 
    # names to display, default (display all columns) 
    # Type: string
    input_columns: ''

    # Boolean indicating whether to output 
    # input, output and secret names 
    # as markdown links 
    # Type: boolean
    # Default: "true"
    markdown_links: ''

    # Path to the output file
    # Type: string
    # Default: "README.md"
    output: ''

    # List of action.yml **output** column 
    # names to display, default (display all columns) 
    # Type: string
    output_columns: ''

    # Repository name with owner. For 
    # example, tj-actions/auto-doc 
    # Type: string
    # Default: "${{ github.repository }}"
    repository: ''

    # Boolean Indicating whether the file 
    # is a reusable workflow 
    # Type: string
    reusable: ''

    # List of reusable workflow **input** 
    # column names to display, default 
    # (display all columns) 
    # Type: string
    reusable_input_columns: ''

    # List of reusable workflow **output** 
    # column names to display, default 
    # (display all columns) 
    # Type: string
    reusable_output_columns: ''

    # List of reusable workflow **secret** 
    # column names to display, default 
    # (display all columns) 
    # Type: string
    reusable_secret_columns: ''

    # GitHub token or Personal Access 
    # Token used to fetch the 
    # repository latest tag. 
    # Type: string
    # Default: "${{ github.token }}"
    token: ''

    # Enable code block documentation
    # Type: boolean
    # Default: "false"
    use_code_blocks: ''

    # Use the major version of 
    # the repository tag e.g v1.0.0 
    # -> v1 
    # Type: boolean
    # Default: "false"
    use_major_version: ''

    # The version number to run
    # Type: string
    version: ''

👆 This was generated 👆 using 👉 action.yml

Example workflow

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/checkout@v4
         with:
           fetch-depth: 0  # otherwise, you will failed to push refs to dest repo

       - name: Run auto-doc
         uses: tj-actions/auto-doc@v3

       - 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

Install using Go:

go get -u github.com/tj-actions/auto-doc/v3

Install using Homebrew:

brew install tj-actions/tap/auto-doc

Install using Chocolatey (Windows):

choco install auto-doc

Synopsis

Automatically generate documentation for your custom GitHub action or reusable workflow.

auto-doc [flags]

Flags

    --colMaxWidth string                  Max width of a column. (default "1000")
    --colMaxWords string                  Max number of words per line in a column. (default "6")
-f, --filename string                 config file.
-h, --help                            help for auto-doc
    --inputColumns stringArray            list of input column names. (default [Input,Type,Required,Default,Description])
-m, --markdownLinks                   Names of inputs, outputs and secrets as markdown links.
-o, --output string                   Output file. (default "README.md")
    --outputColumns stringArray           list of output column names. (default [Output,Type,Description])
    --repository string                   Repository name with owner. Example: tj-actions/auto-doc
-r, --reusable                        A reusable workflow.
    --reusableInputColumns stringArray    list of reusable input column names. (default [Input,Type,Required,Default,Description])
    --reusableOutputColumns stringArray   list of reusable output column names. (default [Output,Value,Description])
    --reusableSecretColumns stringArray   list of reusable secrets column names. (default [Secret,Required,Description])
    --token string                        GitHub token or Personal Access Token used to fetch the repository latest tag.
    --useCodeBlocks                       Enable code block documentation.
    --useMajorVersion                     Use the major version of the repository tag. Example: v1.0.0 -> v                 Use the major version of the repository tag. e.g v1.0.0 -> v1