auto-doc

GitHub Action that generates beautiful, easy-to-read markdown tables with just a few lines of code. Say goodbye to manual table creation 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, secrets.
Show deprecated inputs.
Fast and always up-to-date documentation.

Usage

Add the Inputs and/or Outputs and/or Secrets (only supported by reusable workflows) and/or Description (only supported by actions) H2 header to any markdown file.

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

Inputs

INPUT	TYPE	REQUIRED	DEFAULT	DESCRIPTION
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	`"5"`	Max number of words per line in a column
filename	string	false	`"action.yml"`	Path to the yaml file
input_columns	string	false		List of action.yml input columns names to display, default (display all columns)
markdown_links	string	false	`"true"`	Boolean indicating whether to output input, output and secret names as markdown links
output	string	false	`"README.md"`	Path to the output file
output_columns	string	false		List of action.yml output column names to display, default (display all columns)
repository	string	false	`"${{ github.repository }}"`	Repository name with owner. For example, tj-actions/auto-doc
reusable	string	false		Boolean Indicating whether the file is a reusable workflow
reusable_input_columns	string	false		List of reusable workflow input column names to display, default (display all columns)
reusable_output_columns	string	false		List of reusable workflow output column names to display, default (display all columns)
reusable_secret_columns	string	false		List of reusable workflow secret column names to display, default (display all columns)
token	string	false	`"${{ github.token }}"`	GitHub token or Personal Access Token used to fetch the repository latest tag.
use_code_blocks	string	false	`"false"`	Enable code block documentation
use_major_version	string	false	`"false"`	Use the major version of the repository tag e.g v1.0.0 -> v1
version	string	false		The version number to run

👆 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/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/verify-changed-files@v8.6
         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