andreas-aman / auto-doc Goto Github PK

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.

• 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.

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

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

👆 This is 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/[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@v2

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

brew install tj-actions/tap/auto-doc

choco install auto-doc

Automatically 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])
-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:

This package was created with Cookiecutter using cookiecutter-action

• cobra
• goreleaser

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

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