Github Actionsのドキュメントを自動生成する

# 概要

Github Actionsのドキュメントを自動生成する方法についてご紹介します！
https://github.com/gizumon/github-actions-documenter#github-actions-documenter

# 対象

#### ターゲットユーザー🙎‍♂️
* [Custom Actions](https://docs.github.com/ja/actions/creating-actions/about-custom-actions) / [Reusable Workflows](https://docs.github.com/ja/actions/using-workflows/reusing-workflows)を
  * 作ってみたけど、ドキュメント作ってない、、、
  * 作ってみたけど、ドキュメント作るのめんどくさかった、、、
  * 作っているけど、ドキュメントフォーマットがばらばら、、、
  * これからたくさん作る機会がありそう

#### 対応ワークフロー📄

Github Actionsで再利用可能な部品を作成する、下記ドキュメントの自動生成に対応しています。
* [Custom Actions](https://docs.github.com/ja/actions/creating-actions/about-custom-actions)
* [Reusable Workflows](https://docs.github.com/ja/actions/using-workflows/reusing-workflows)
  * Docker Container Action
  * Javascript Action
  * Composite Action

#### 対応機能🛠

* __① ymlファイルからマークダウンドキュメントの自動生成__
  * アノテーション(@)を使って、ドキュメントにサンプル(@example)や注釈(@note)を追加することも可能です。([例](https://github.com/gizumon/github-actions-documenter/blob/main/.github/workflows/github-actions-documenter.yml#L1))
  * 生成されるドキュメントのフォーマットは[こちら](https://github.com/marketplace/actions/github-actions-documenter#-custom-actions-)を参照ください。
* __② 生成したマークダウンドキュメントを指定したファイルへ出力__
  * 既存のファイルへの追加するか、新規ファイルへの上書きするかなどを指定することができます。
* __③　出力したファイルをコミット__
* __④　新規プルリクエストの作成__
  * 変更コミットの新規プルリクエストを作成することができます。
    * プルリクエストを作成しない場合は、対象ブランチに変更が追加されます。

# 使い方

自動生成したいymlが存在するリポジトリに下記の様なワークフローを追加ください。([追加例](https://github.com/gizumon/github-actions-documenter/blob/main/.github/workflows/caller-test.yml))

```yml:使い方サンプル
name: "Basic Sample"
on:
  push:
    branches:
      - main
    paths:
      - '*/action.yml'
      - '*/action.yaml'
      - '.github/workflows/*.yml'
  pull_request:
    paths:
      - '*/action.yml'
      - '*/action.yml'
      - '.github/workflows/*.yml'

jobs:
  documentation:
    uses: gizumon/github-actions-documenter/.github/workflows/github-actions-documenter.yml@main
    with:
      filepath: README.md
```

なお、GHE上などで、Reusable Workflowsを呼び出せない場合には[こちらのワークフロー](https://github.com/gizumon/github-actions-documenter/blob/main/.github/workflows/github-actions-documenter.yml)をコピーして、呼び出せる箇所に配置して使って頂ければと思います。

:::message
今のところ、Custom Actions内では、ドキュメントの生成のみしか対応しておらず、ワークフロー内でファイルへの追加(or 生成)とコミットを実行しています。
将来的にはこちらもCustom Actionsに統合していければと思っていますが、一旦上記の様に使って頂ければと思います。
:::

## サポートインターフェース

Reusable Workflowは下記のインターフェースをサポートしています。(最新の情報は、[こちら](https://github.com/gizumon/github-actions-documenter#inputs)をご確認ください。)

```yml:ワークフロー呼び出し例
    uses: gizumon/github-actions-documenter/.github/workflows/github-actions-documenter.yml@main
    with:
      filepath: README.md
      overwrite: true
      make-pull-request: true
```

| # | 必須 | 名前 | 説明 |
| :--- | :---: | :--- | :--- |
| 1 | ✅  | filepath | 生成したドキュメントを書き込むファイルパス(デフォルト: README.md) |
| 2 |  | overwrite | 上書きフラグ。trueの場合、ファイルは上書きされます。falseの場合、ファイルに追記されます。(デフォルト: false) |
| 3 | | make-pull-request | プルリクエスト作成フラグ。trueの場合、refブランチへ新規プルリクエストを作成します。falseの場合、refブランチへ直接プッシュします。(デフォルト: false)|

## 生成ドキュメントイメージ

#### 入力引数 (`on.workflow_call.inputs`)

```yml:対象yml
...
on:
  workflow_call:
    inputs:
      filepath:
        required: true
        type: string
        default: README.md
        description: "Filepath to write the generated reusable workflow document. (default: README.md)"
      overwrite:
        required: false
        type: boolean
        default: false
        description: "If true, overwrite the filepath file. (default: false)"
      make-pull-request:
        required: false
        type: boolean
        default: false
        description: "If true, make a pull request to ref branch. If false, directly push to ref branch. (default: false)"
...
```

↓ 生成マークダウン ↓

![on.workflow_call.inputs](https://storage.googleapis.com/zenn-user-upload/c557d6974a8f-20220924.png)

#### 出力引数 (`on.workflow_call.outputs`)

```yml:対象yml
...
on:
  workflow_call:
    ...
    outputs:
      output:
        description: "GitHub Actions markdown document (Reusable Workflow and Custom Actions)"
        value: "${{ jobs.documentation.outputs.output }}"
...
```

↓ 生成マークダウン ↓

![on.workflow_call.outputs](https://storage.googleapis.com/zenn-user-upload/96c30f0013c9-20220924.png)

#### サンプル例 (`comment:@example`)

```yml:対象comment
# @example=### Example1: Basic example
# name: "Basic example"
# on:
#   pull_request:
#     paths:
#       - '.github/workflows/*.yml'
# jobs:
#   test:
#     uses: gizumon/github-actions-documenter/.github/workflows/github-actions-documenter.yml@main
#     with:
#       filepath: README.md
```

↓ 生成マークダウン ↓
![@example](https://storage.googleapis.com/zenn-user-upload/74e49e0a6ff7-20220924.png)

#### 注釈 (`comment:@note`)

```yml:対象comment
# @note=### Support events
# - push
# - pull_request
```

↓ 生成マークダウン ↓
![@note](https://storage.googleapis.com/zenn-user-upload/70c1be99702b-20220924.png)

# 最後に

* 不具合やご要望がありましたら、[こちらでIssue](https://github.com/gizumon/github-actions-documenter/issues/new)を発行して頂けるととってもありがたいです🙇‍♂️
* まだまだ私自身Github Actionsお勉強中のため、フィードバックありましたらどしどしコメントお願いします！
  * 使い方等分からない点などもお気軽にコメント頂ければと思います!

---

https://github.com/gizumon
https://twitter.com/gizumon5