auto-doc

README

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
• 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)
markdown_links	string	false	"false"	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 :point_right: 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])
-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])

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

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

Documentation

Overview

Copyright © 2021 Tonye Jack <jtonye@ymail.com>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.