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.
- Document your custom Github action using the
action.ymlfile. - 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.ymlfile which includes all inputs. - Show deprecated inputs.
- Fast and always up-to-date documentation.
Add any of the supported headings as a H2 header in any location of your markdown file.
InputsOutputsSecrets(only supported by reusable workflows)Description(only supported by actions)
- 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
- 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
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"go get -u github.com/tj-actions/auto-doc/v3brew install tj-actions/tap/auto-docchoco install auto-docAutomatically generate documentation for your custom GitHub action or reusable workflow.
auto-doc [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:
This package was created with Cookiecutter using cookiecutter-action
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.
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!