Skip to content

:octocat: Github action that turns your reusable workflows and custom actions into easy to read markdown tables.

License

Notifications You must be signed in to change notification settings

tj-actions/auto-doc

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

Ubuntu Mac OS Windows Public workflows that use this action.

CI Coverage Update release version. codecov

Codacy Badge Go Report Card Go Reference

All Contributors

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

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/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

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

Buy me a coffee

Credits

This package was created with Cookiecutter using cookiecutter-action

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
Andreas Γ…man

πŸ’» πŸ“–
Viacheslav Kudinov
Viacheslav Kudinov

πŸ’» ⚠️
Christophe Furmaniak
Christophe Furmaniak

πŸ’» ⚠️
Mike W
Mike W

πŸ’» πŸ“–

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