docs: Add versioning plugin for docs and update workflows (#1877)

phipag · web-flow · commit fb9d437ed6a7 · 2025-06-12T12:04:17.000+02:00
diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
@@ -1,7 +1,7 @@
-# Build Docs
+# Build Latest Docs
 #
 # Description:
-#   Builds the docs and stores them in S3 to be served by our docs platform
+#   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
@@ -15,17 +15,13 @@
 on:
   workflow_dispatch:
     inputs:
-      alias:
+      version:
+        description: "Version to build and publish docs (1.28.0, develop)"
+        required: true
         type: string
-        required: false
-        description: |
-          Alias to deploy the documentation into, this is mostly for testing pre-release
-          versions of the documentation, such as beta versions or snapshots.
 
-          https://docs.powertools.aws.dev/lambda/java/<alias>
-
-name: Build Docs
-run-name: Build Docs - ${{ contains(github.head_ref, 'main') && 'main' || inputs.alias }}
+name: Build Latest Docs
+run-name: Build Latest Docs - ${{ inputs.version }}
 
 permissions:
   contents: read
@@ -38,28 +34,58 @@ jobs:
       id-token: write
     environment: Docs
     steps:
-      - name: Sanity Check
-        if: ${{ github.head_ref != 'main' || inputs.alias == '' }}
-        run:
-          echo "::error::No buildable docs"
-
       - name: Checkout Repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-        with: 
+        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
-          cp -R site/* dist/
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@ececac1a45f3b08a01d2dd070d28d111c5fe6722
         with:
           aws-region: us-east-1
           role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }}
-      - name: Deploy
+      - name: Deploy Docs (Version)
+        env:
+          VERSION: ${{ inputs.version }}
+          ALIAS: "latest"
         run: |
           aws s3 sync \
-            dist \
-            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ github.head_ref == 'main' && '' || format('{0}/', inputs.alias )}}
+            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
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -20,7 +20,7 @@
 #
 # Triggers:
 #   - workflow_dispatch
-# 
+#
 #  Secrets:
 #   - RELEASE.GPG_SIGNING_KEY
 #   - RELEASE.OSSRH_JIRA_USERNAME
@@ -39,23 +39,23 @@ on:
         type: boolean
         description: Create snapshot release
         default: false
-      skip_checks: 
+      skip_checks:
         type: boolean
         description: Skip quality checks
         default: false
       skip_publish:
         type: boolean
         description: Skip publish to Maven Central
         default: false
-      continue_on_error: 
+      continue_on_error:
         type: boolean
         description: Continue to build if there's an error in quality checks
         default: false
 
 name: Release
 run-name: Release – ${{ inputs.version }}
 
-permissions: 
+permissions:
   contents: read
 
 env:
@@ -124,7 +124,7 @@ jobs:
 
   quality:
     runs-on: ubuntu-latest
-    needs: 
+    needs:
       - version_seal
     if: ${{ inputs.skip_checks == false }}
     permissions:
@@ -211,7 +211,7 @@ jobs:
           MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
           MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
           GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
-  
+
   create_pr:
     runs-on: ubuntu-latest
     if: ${{ inputs.snapshot == false && always() && !contains(needs.*.result, 'failure') && !contains(needs.*.result, 'cancelled') }}
@@ -280,14 +280,49 @@ jobs:
           mkdir -p dist
           docker build -t squidfunk/mkdocs-material ./docs/
           docker run --rm -t -v ${PWD}:/docs squidfunk/mkdocs-material build
-          cp -R site/* dist/
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@ececac1a45f3b08a01d2dd070d28d111c5fe6722
         with:
           aws-region: us-east-1
           role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }}
-      - name: Deploy
+      - name: Deploy Docs (Version)
+        env:
+          VERSION: ${{ inputs.version }}
+          ALIAS: 'latest'
         run: |
           aws s3 sync \
-            dist \
-            s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/
+            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
diff --git a/docs/overrides/main.html b/docs/overrides/main.html
@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+You're not viewing the latest version.
+<a href="{{ '../' ~ base_url }}">
+  <strong>Click here to go to latest.</strong>
+</a>
+{% endblock %}
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -123,6 +123,9 @@ extra_javascript:
 extra:
   powertools:
     version: 1.20.2 # to update after each release (we do not want snapshot version here)
+  version:
+    provider: mike
+    default: latest
 
 repo_url: https://github.com/aws-powertools/powertools-lambda-java
 edit_uri: edit/main/docs
