build-docs.yml

# Build Latest Docs
#
# Description:
#   Builds the latest docs and stores them in S3 to be served by our docs platform
#
#   The workflow allows us to build to the main location (/lambda/java/) and to an alias
#   (i.e. /lambda/java/preview/) if needed
#
# Triggers:
#   - workflow_dispatch
#
# Inputs:
#   alias – subdirectory to store the docs in for previews or in progress work

on:
  workflow_dispatch:
    inputs:
      version:
        description: "Version to build and publish docs (1.28.0, develop)"
        required: true
        type: string

name: Build Latest Docs
run-name: Build Latest Docs - ${{ inputs.version }}

permissions: {}

jobs:
  docs:
    runs-on: ubuntu-latest
    permissions:
      contents: read   # checkout repository
      id-token: write  # OIDC for AWS credentials
    environment: Docs
    steps:
      - name: Checkout Repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
        with:
          fetch-depth: 0
      - name: Build
        run: |
          mkdir -p dist
          docker build -t squidfunk/mkdocs-material ./docs/
          docker run --rm -t -v ${PWD}:/docs squidfunk/mkdocs-material build
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
        with:
          aws-region: us-east-1
          role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }}
      - name: Deploy Docs (Version)
        env:
          VERSION: ${{ inputs.version }}
          ALIAS: "latest"
        run: |
          aws s3 sync \
            site/ \
            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.VERSION }}/
      - name: Deploy Docs (Alias)
        env:
          VERSION: ${{ inputs.version }}
          ALIAS: "latest"
        run: |
          aws s3 sync \
            site/ \
            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.ALIAS }}/
      - name: Deploy Docs (Version JSON)
        env:
          VERSION: ${{ inputs.version }}
          ALIAS: "latest"
        # 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-java/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-java/versions.json