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.

Table of Contents

• Usage
  • Supported Headings
  • Example
• Inputs
• Example workflow
• CLI
  • Installation
    • Install using Go:
    • Install using Homebrew:
    • Install using Chocolatey (Windows):
  • Synopsis
  • Flags
• Credits
• Report Bugs
• Contributors ✨

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

1. 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

• 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
• 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.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Andreas Åman 💻 📖

Viacheslav Kudinov 💻 ⚠️

Christophe Furmaniak 💻 ⚠️

Mike W 💻 📖

This project follows the all-contributors specification. Contributions of any kind welcome!