Automatically Update Open Source Project API Documentation Using GitHub Actions

Scenario

When updating an open-source library, it is common to add, remove, or modify old interfaces. These changes can be frequent and subtle, making manual documentation updates a tedious task. Therefore, an automated pipeline is needed to solve this problem. Once a new version is released, the API documentation will be automatically updated.

Technologies Involved

• api-extractor, used to extract interface information
• api-documenter, processes the extracted information into markdown files
• docusaurus, a well-known documentation framework
• GitHub Actions, runs the pipeline to automatically commit documentation files

In this case, I prefer to manage Docusaurus separately from my main code repository. This involves the ability to commit content to a third-party repository. This article uses mind-elixir-core and mind-elixir/docs as examples.

Configuration File

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

Configuration Analysis

The key to the push operation is configuring secrets.PAT in the project. GitHub Actions running in the current project do not seem to require a PAT, but if pushing to another project, a PAT is necessary.

A PAT means personal access token, which grants you permission to push to the target GitHub repository.

Steps to obtain a PAT:

• Verify your email
• Click on your GitHub avatar in the top right corner, select Settings
• In the left sidebar, select Developer settings
• In the left sidebar, select Personal access tokens

There are currently two types of tokens to choose from, but using GitHub’s token within GitHub itself should generally be fine.

After obtaining the PAT, configure the secret in the repository where the Action needs to run. The Action will automatically retrieve it during execution. The rest of the content is straightforward automation scripts, so I won’t elaborate further. The overall process is summarized below ↓

Summary

The basic process of the GitHub Action is:

• Pull the project
• Build the project
• Publish to npm (requires npm Token)
• Use api-extractor to extract interface information and use api-documenter to generate markdown files
• Pull the documentation project
• Copy the generated markdown documentation files to the documentation project (copied three times due to i18n)
• Commit the updates to the documentation repository
• The documentation repository will then automatically trigger its own webhook to build the documentation site

With this setup, after releasing a new version of mind-elixir-core, the API section of the documentation website will be automatically updated.