reusable-publish-docs.yml

name: Reusable Publish docs

env:
  BRANCH: main
  ORIGIN: aws-powertools/powertools-lambda-typescript
  VERSION: ""

on:
  workflow_call:
    secrets:
      AWS_DOCS_ROLE_ARN:
        description: zomg
        required: false
      AWS_DOCS_BUCKET:
        description: zomg
        required: false
    inputs:
      version:
        description: "Version to build and publish docs (1.28.0, develop)"
        required: true
        type: string
      alias:
        description: "Alias to associate version (latest, stage)"
        required: true
        type: string
      detached_mode:
        description: "Whether it's running in git detached mode to ensure git is sync'd"
        required: false
        default: false
        type: boolean

permissions:
  contents: write
  id-token: write
  pages: write

jobs:
  publish-docs:
    runs-on: ubuntu-latest
    environment: Docs
    steps:
      - name: Checkout code
        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
        with:
          # While `fetch-depth` is used to allow the workflow to later commit & push the changes.
          fetch-depth: 0
      - name: Setup NodeJS
        uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
        with:
          node-version: "20"
          cache: "npm"
      - name: Setup dependencies
        uses: ./.github/actions/cached-node-modules
      - name: Set up Python
        uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c # v5.0.0
        with:
          python-version: "3.11"
      - name: Install doc generation dependencies
        run: |
          pip install --require-hashes -r docs/requirements.txt
      - name: Setup doc deploy
        run: |
          git config --global user.name Docs deploy
          git config --global user.email aws-devax-open-source@amazon.com
      - name: Git refresh tip (detached mode)
        # Git Detached mode (release notes) doesn't have origin
        if: ${{ inputs.detached_mode }}
        run: |
          git config pull.rebase true
          git config remote.origin.url >&- || git remote add origin https://github.com/"$ORIGIN"
          git pull origin "$BRANCH"
      - name: Normalize Version Number
        run: echo "VERSION=$(echo ${{ inputs.version }} | sed 's/v//')" >> $GITHUB_ENV
      - name: Build docs website and API reference
        env:
          ALIAS: ${{ inputs.alias }}
        run: |
          rm -rf site
          mkdocs build
          mike deploy --update-aliases --no-redirect ${{ env.VERSION }} ${{ env.ALIAS }} --branch backup-gh-pages
          # Set latest version as a default
          mike set-default latest --branch backup-gh-pages
      - name: Build API docs
        run: |
          rm -rf api
          npm run docs-generateApiDoc
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@010d0da01d0b5a38af31e9c3470dbfdabdecca3a # v4.0.1
        with:
          aws-region: us-east-1
          role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }}
          mask-aws-account-id: true
      - name: Copy API Docs
        run: |
          cp -r api site/
      - name: Create Artifact (Site)
        uses: actions/upload-artifact@26f96dfa697d77e81fd5907df203aa23a56210a8 # v4.3.0
        with:
          name: site
          path: site
      - name: Deploy Docs (Version)
        env:
          VERSION: ${{ inputs.version }}
          ALIAS: ${{ inputs.alias }}
        run: |
          aws s3 sync \
            site/ \
            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-typescript/${{ env.VERSION }}/
      - name: Deploy Docs (Alias)
        env:
          VERSION: ${{ inputs.version }}
          ALIAS: ${{ inputs.alias }}
        run: |
          aws s3 sync \
            site/ \
            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-typescript/${{ env.ALIAS }}/
      - name: Deploy Docs (Version JSON)
        env:
          VERSION: ${{ inputs.version }}
          ALIAS: ${{ inputs.alias }}
        # We originally used "mike" from PyPi to manage versions for us, but since we moved to S3, we can't use it to manage versions any more.
        # Instead, we're using some shell script that manages the versions.
        #
        # Operations:
        #   1. Download the versions.json file from S3
        #   2. Find any reference to the alias and delete it from the versions file
        #   3. This is voodoo (don't use JQ):
        #      - we assign the input as $o and the new version/alias as $n,
        #      - we check if the version number exists in the file already (for republishing docs)
        #      - if it's an alias (stage/latest/*) or old version, we do nothing and output $o (original input)
        #      - if it's a new version number, we add it at position 0 in the array.
        #   4. Once done, we'll upload it back to S3.
        run: |
          aws s3 cp \
            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-typescript/versions.json \
            versions_old.json
          jq 'del(.[].aliases[] | select(. == "${{ env.ALIAS }}"))' < versions_old.json > versions_proc.json
          jq '. as $o | [{"title": "${{ env.VERSION }}", "version": "${{ env.VERSION }}", "aliases": ["${{ env.ALIAS }}"] }] as $n | $n | if .[0].title | test("[a-z]+") or any($o[].title == $n[0].title;.) then [($o | .[] | select(.title == $n[0].title).aliases += $n[0].aliases | . )] else $n + $o end' < versions_proc.json > versions.json
          aws s3 cp \
            versions.json \
            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-typescript/versions.json