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.
• Fast and always up-to-date documentation.

Table of Contents

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

Usage

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

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

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)
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)
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)
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@v2.4.0
         with:
           fetch-depth: 0  # otherwise, you will failed to push refs to dest repo

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

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

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])
-o, --output string                   Output file (default "README.md")
--outputColumns stringArray           list of output column names (default [Output,Type,Description])
-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])

• 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 💻 ⚠️

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