Actualizar automáticamente la documentación de la API de un proyecto de código abierto usando GitHub Actions

Escenario

Al actualizar una biblioteca de código abierto, es común agregar, eliminar o modificar interfaces antiguas. Estos cambios pueden ser frecuentes y sutiles, lo que hace que las actualizaciones manuales de la documentación sean una tarea tediosa. Por lo tanto, se necesita una canalización automatizada para resolver este problema. Una vez que se lanza una nueva versión, la documentación de la API se actualizará automáticamente.

Tecnologías Involucradas

• api-extractor, utilizado para extraer información de interfaces
• api-documenter, procesa la información extraída en archivos markdown
• docusaurus, un conocido marco de documentación
• GitHub Actions, ejecuta la canalización para comprometer automáticamente los archivos de documentación

En este caso, prefiero gestionar Docusaurus por separado de mi repositorio de código principal. Esto implica la capacidad de comprometer contenido a un repositorio de terceros. Este artículo utiliza mind-elixir-core y mind-elixir/docs como ejemplos.

Archivo de Configuración

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

Análisis de Configuración

La clave para la operación de push es configurar secrets.PAT en el proyecto. Las GitHub Actions que se ejecutan en el proyecto actual no parecen requerir un PAT, pero si se empuja a otro proyecto, es necesario un PAT.

Un PAT significa token de acceso personal, que te otorga permiso para empujar al repositorio de GitHub de destino.

Pasos para obtener un PAT:

• Verifica tu correo electrónico
• Haz clic en tu avatar de GitHub en la esquina superior derecha, selecciona Settings
• En la barra lateral izquierda, selecciona Developer settings
• En la barra lateral izquierda, selecciona Personal access tokens

Actualmente hay dos tipos de tokens para elegir, pero usar el token de GitHub dentro de GitHub en sí debería estar bien en general.

Después de obtener el PAT, configura el secreto en el repositorio donde necesita ejecutarse la Acción. La Acción lo recuperará automáticamente durante la ejecución. El resto del contenido son scripts de automatización sencillos, por lo que no me extenderé más. El proceso general se resume a continuación ↓

Resumen

El proceso básico de la GitHub Action es:

• Clonar el proyecto
• Construir el proyecto
• Publicar en npm (requiere Token de npm)
• Usar api-extractor para extraer información de interfaces y usar api-documenter para generar archivos markdown
• Clonar el proyecto de documentación
• Copiar los archivos de documentación markdown generados al proyecto de documentación (copiados tres veces debido a i18n)
• Comprometer las actualizaciones al repositorio de documentación
• El repositorio de documentación luego activará automáticamente su propio webhook para construir el sitio de documentación

Con esta configuración, después de lanzar una nueva versión de mind-elixir-core, la sección de API del sitio web de documentación se actualizará automáticamente.