Skip to content

Warning

You're viewing an older version of this GitHub Action. Do you want to see the latest version instead?

auto-doc

Actions
Document your github action or reusable workflow with ease
v3.0.0
Star (47)

Ubuntu Mac OS Windows Public workflows that use this action.

Coverage codecov Go Reference Go Report Card CI Update release version. Codacy Badge

All Contributors

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.

Table of Contents

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@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)
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/[email protected]
         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/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])
-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])
-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])

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

💻 ⚠️

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

auto-doc is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.

About

Document your github action or reusable workflow with ease
v3.0.0

auto-doc is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.