skip to content
usubeni fantasy logo Usubeni Fantasy

GitHub Actionsを使用してオープンソースプロジェクトのAPIドキュメントを自動更新する

/ 4 min read

This Post is Available In: CN EN ES JA

シナリオ

オープンソースライブラリを更新する際、古いインターフェースを追加、削除、または変更することが一般的です。これらの変更は頻繁で微妙な場合が多く、手動でのドキュメント更新は面倒な作業になります。したがって、この問題を解決するために自動化されたパイプラインが必要です。新しいバージョンがリリースされると、APIドキュメントが自動的に更新されます。

使用技術

  • api-extractor、インターフェース情報を抽出するために使用
  • api-documenter、抽出された情報をMarkdownファイルに処理
  • docusaurus、有名なドキュメントフレームワーク
  • GitHub Actions、ドキュメントファイルを自動的にコミットするためのパイプラインを実行

この場合、Docusaurusをメインのコードリポジトリとは別に管理することを好みます。これには、サードパーティのリポジトリにコンテンツをコミットする機能が含まれます。この記事では、mind-elixir-coremind-elixir/docsを例として使用します。

設定ファイル

name: Node.js Package
on:
release:
types: [created]
workflow_dispatch:
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: pnpm/action-setup@v2
with:
version: 8
- uses: actions/setup-node@v3
with:
node-version: 18
registry-url: "https://registry.npmjs.org"
cache: "pnpm"
- run: pnpm i
- run: npm run build
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{secrets.npm_token}}
- name: Checkout docs repository
uses: actions/checkout@v3
with:
repository: mind-elixir/docs
token: ${{ secrets.PAT }}
path: me-docs
- name: Generate API documentation
run: |
npm run doc
npm run doc:md
- name: Copy build results to docs repository
run: |
cp -r ./md/* ./me-docs/docs/api
cp -r ./md/* ./me-docs/i18n/ja/docusaurus-plugin-content-docs/current
cp -r ./md/* ./me-docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current
- name: Push changes to docs repository
run: |
cd me-docs
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add .
if git diff-index --quiet HEAD; then
echo "No changes to commit"
else
git commit -m "Update API documentation"
git push
fi

設定分析

push操作の鍵は、プロジェクトでsecrets.PATを設定することです。現在のプロジェクトで実行されるGitHub ActionsはPATを必要としないようですが、別のプロジェクトにプッシュする場合はPATが必要です。

PATとは、ターゲットのGitHubリポジトリにプッシュする権限を与える個人アクセストークンのことです。

PATを取得する手順:

  • メールを確認する
  • 右上のGitHubアバターをクリックし、Settingsを選択
  • 左側のサイドバーでDeveloper settingsを選択
  • 左側のサイドバーでPersonal access tokensを選択

現在、選択できるトークンは2種類ありますが、GitHub内でGitHubのトークンを使用するのが一般的に問題ありません。

PATを取得した後、アクションを実行するリポジトリでシークレットを設定します。アクションは実行中に自動的にそれを取得します。残りの内容は自動化スクリプトなので、詳しくは説明しません。全体のプロセスは以下の通りです ↓

まとめ

GitHub Actionの基本的なプロセスは次のとおりです:

  • プロジェクトをプル
  • プロジェクトをビルド
  • npmに公開(npmトークンが必要)
  • api-extractorを使用してインターフェース情報を抽出し、api-documenterを使用してMarkdownファイルを生成
  • ドキュメントプロジェクトをプル
  • 生成されたMarkdownドキュメントファイルをドキュメントプロジェクトにコピー(i18nのために3回コピー)
  • ドキュメントリポジトリに更新をコミット
  • ドキュメントリポジトリは独自のWebhookを自動的にトリガーしてドキュメントサイトをビルド

この設定により、新しいバージョンのmind-elixir-coreをリリースした後、ドキュメントサイトのAPIセクションが自動的に更新されます。

评论组件加载中……