From 3f8b9e01498fc9e79eb3e17aa1564e5cc201622b Mon Sep 17 00:00:00 2001 From: Philipp Page Date: Thu, 12 Jun 2025 11:50:29 +0200 Subject: [PATCH] Add versioning plugin for docs and update workflows. --- .github/workflows/build-docs.yml | 68 ++++++++++++++++++++++---------- .github/workflows/release.yml | 55 +++++++++++++++++++++----- docs/overrides/main.html | 8 ++++ mkdocs.yml | 3 ++ 4 files changed, 103 insertions(+), 31 deletions(-) create mode 100644 docs/overrides/main.html diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index b1e5a2df7..6ad569bd2 100644 --- 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/ - -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 )}} \ No newline at end of file + 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 index f403f6ca3..590725dc0 100644 --- 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,7 +39,7 @@ on: type: boolean description: Create snapshot release default: false - skip_checks: + skip_checks: type: boolean description: Skip quality checks default: false @@ -47,7 +47,7 @@ on: 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 @@ -55,7 +55,7 @@ on: 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 new file mode 100644 index 000000000..e4c38e21b --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} + +{% block outdated %} +You're not viewing the latest version. + + Click here to go to latest. + +{% endblock %} diff --git a/mkdocs.yml b/mkdocs.yml index 29c34f334..49de3199a 100644 --- 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