GitHub Actionsを使用してオープンソースプロジェクトのAPIドキュメントを自動更新する
/ 4 min read
シナリオ
オープンソースライブラリを更新する際、古いインターフェースを追加、削除、または変更することが一般的です。これらの変更は頻繁で微妙な場合が多く、手動でのドキュメント更新は面倒な作業になります。したがって、この問題を解決するために自動化されたパイプラインが必要です。新しいバージョンがリリースされると、APIドキュメントが自動的に更新されます。
使用技術
- api-extractor、インターフェース情報を抽出するために使用
- api-documenter、抽出された情報をMarkdownファイルに処理
- docusaurus、有名なドキュメントフレームワーク
- GitHub Actions、ドキュメントファイルを自動的にコミットするためのパイプラインを実行
この場合、Docusaurusをメインのコードリポジトリとは別に管理することを好みます。これには、サードパーティのリポジトリにコンテンツをコミットする機能が含まれます。この記事では、mind-elixir-coreとmind-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セクションが自動的に更新されます。