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@8e5e7e5ab8b370d6c329ec480221332ada57f0ab  # v3.5.2
        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@64ed1c7eab4cce3362f8c340dee64e5eaeef8f7c # v3.6.0
        with:
          node-version: "18"
          cache: "npm"
      - name: Setup dependencies
        uses: ./.github/actions/cached-node-modules
      - name: Set up Python
        uses: actions/setup-python@57ded4d7d5e986d7296eab16560982c6dd7c923b # v4.6.0
        with:
          python-version: "3.8"
      - name: Install doc generation dependencies
        run: |
          pip install --upgrade pip 
          pip install -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@e1e17a757e536f70e52b5a12b2e8d1d1c60e04ef # v2.0.0
        with:
          aws-region: us-east-1
          role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }}
      - name: Copy API Docs
        run: |
          cp -r api 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 == "${{ env.VERSION }}";.) then $o else $n + $o end' < versions_proc.json > versions.json
          aws s3 cp \
            versions.json \
            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-typescript/versions.json