chore(ci): create reusable docs publishing workflow

.github/workflows/on_push_docs.yml

@@ -0,0 +1,35 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - develop
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "examples/**"
+
+jobs:
+  changelog:
+    permissions:
+      contents: write
+    uses: ./.github/workflows/reusable_publish_changelog.yml
+
+  release-docs:
+    needs: changelog
+    permissions:
+      contents: write
+      pages: write
+    uses: ./.github/workflows/reusable_publish_docs.yml
+    with:
+      version: develop
+      alias: stage
+# Maintenance: Only necessary in repo migration
+# - name: Create redirect from old docs
+#   run: |
+#     git checkout gh-pages
+#     test -f 404.html && echo "Redirect already set" && exit 0
+#     git checkout develop -- 404.html
+#     git add 404.html
+#     git commit -m "chore: set docs redirect" --no-verify
+#     git push origin gh-pages -f

.github/workflows/on_release_notes.yml

@@ -69,16 +69,16 @@ jobs:
         id: release_version
         # transform tag format `v<version` to `<version`
         run: |
-          RELEASE_VERSION=${RELEASE_TAG_VERSION:1}
-          echo "RELEASE_VERSION=${RELEASE_VERSION}" >> $GITHUB_ENV
+          RELEASE_VERSION="${RELEASE_TAG_VERSION:1}"
+          echo "RELEASE_VERSION=${RELEASE_VERSION}" >> "$GITHUB_ENV"
           echo "::set-output name=RELEASE_VERSION::${RELEASE_VERSION}"
       - name: Install dependencies
         run: make dev
       - name: Run all tests, linting and baselines
         if: ${{ !inputs.skip_code_quality }}
         run: make pr
       - name: Bump package version
-        run: poetry version ${RELEASE_VERSION}
+        run: poetry version "${RELEASE_VERSION}"
       - name: Build python package and wheel
         if: ${{ !inputs.skip_pypi }}
         run: poetry build
@@ -101,7 +101,7 @@ jobs:
           role-to-assume: ${{ secrets.AWS_SAR_ROLE_ARN }}
       - name: publish lambda layer in SAR by triggering the internal codepipeline
         run: |
-          aws ssm put-parameter --name "powertools-python-release-version" --value $RELEASE_VERSION --overwrite
+          aws ssm put-parameter --name "powertools-python-release-version" --value "$RELEASE_VERSION" --overwrite
           aws codepipeline start-pipeline-execution --name ${{ secrets.AWS_SAR_PIPELINE_NAME }}
 
   changelog:
@@ -115,47 +115,11 @@ jobs:
     permissions:
       contents: write
       pages: write
-    runs-on: ubuntu-latest
-    env:
-      RELEASE_VERSION: ${{ needs.release.outputs.RELEASE_VERSION }}
-    steps:
-      - uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-      - name: Git client setup and refresh tip
-        run: |
-          git config user.name "Release bot"
-          git config user.email "[email protected]"
-          git config pull.rebase true
-          git config remote.origin.url >&- || git remote add origin https://github.com/$origin # Git Detached mode (release notes) doesn't have origin
-          git pull origin $BRANCH
-      - name: Install poetry
-        run: pipx install poetry
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.8"
-          cache: "poetry"
-      - name: Install dependencies
-        run: make dev
-      - name: Build docs website and API reference
-        run: |
-          make release-docs VERSION=${RELEASE_VERSION} ALIAS="latest"
-          poetry run mike set-default --push latest
-      - name: Release API docs to release version
-        uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # v3.8.0
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./api
-          keep_files: true
-          destination_dir: ${{ env.RELEASE_VERSION }}/api
-      - name: Release API docs to latest
-        uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # v3.8.0
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./api
-          keep_files: true
-          destination_dir: latest/api
+    uses: ./.github/workflows/reusable_publish_docs.yml
+    with:
+      version: ${{ needs.release.outputs.RELEASE_VERSION }}
+      alias: latest
+      detached_mode: true
 
   post_release:
     needs: release

.github/workflows/rebuild_latest_docs.yml

@@ -5,14 +5,13 @@ name: Rebuild latest docs
 #
 # 1. Trigger "Rebuild latest docs" workflow manually: https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow
 # 2. Use the latest version released under Releases e.g. v1.22.0
-# 3. Set `Build and publish docs only` field to `true`
 
 on:
   workflow_dispatch:
     inputs:
       latest_published_version:
         description: "Latest PyPi published version to rebuild latest docs for, e.g. v1.26.7"
-        default: "v1.26.7"
+        default: "v1.28.0"
         required: true
 
 jobs:
@@ -21,49 +20,12 @@ jobs:
       contents: write
     uses: ./.github/workflows/reusable_publish_changelog.yml
 
-  release:
+  release-docs:
     needs: changelog
-    # Force Github action to run only a single job at a time (based on the group name)
-    # This is to prevent "race-condition" in publishing a new version of doc to `gh-pages`
-    concurrency:
-      group: on-docs-rebuild
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-      - name: Install poetry
-        run: pipx install poetry
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.8"
-          cache: "poetry"
-      - name: Set release notes tag
-        run: |
-          RELEASE_TAG_VERSION=${{ github.event.inputs.latest_published_version }}
-          echo "RELEASE_TAG_VERSION=${RELEASE_TAG_VERSION:1}" >> $GITHUB_ENV
-      - name: Install dependencies
-        run: make dev
-      - name: Setup doc deploy
-        run: |
-          git config --global user.name Docs deploy
-          git config --global user.email [email protected]
-      - name: Build docs website and API reference
-        run: |
-          make release-docs VERSION=${RELEASE_TAG_VERSION} ALIAS="latest"
-          poetry run mike set-default --push latest
-      - name: Release API docs to release version
-        uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # v3.8.0
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./api
-          keep_files: true
-          destination_dir: ${{ env.RELEASE_TAG_VERSION }}/api
-      - name: Release API docs to latest
-        uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # v3.8.0
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./api
-          keep_files: true
-          destination_dir: latest/api
+    permissions:
+      contents: write
+      pages: write
+    uses: ./.github/workflows/reusable_publish_docs.yml
+    with:
+      version: ${{ inputs.latest_published_version }}
+      alias: latest

.github/workflows/reusable_publish_docs.yml

@@ -0,0 +1,83 @@
+name: Reusable publish documentation
+
+env:
+  BRANCH: develop
+  ORIGIN: awslabs/aws-lambda-powertools-python
+
+on:
+  workflow_call:
+    inputs:
+      version:
+        description: "Version to build and publish docs (v1.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
+  pages: write
+
+jobs:
+  publish_docs:
+    # Force Github action to run only a single job at a time (based on the group name)
+    # This is to prevent "race-condition" in publishing a new version of doc to `gh-pages`
+    concurrency:
+      group: on-docs-rebuild
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Install poetry
+        run: pipx install poetry
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.8"
+          cache: "poetry"
+      - name: Install dependencies
+        run: make dev
+      - name: Git client setup
+        run: |
+          git config --global user.name Docs deploy
+          git config --global user.email [email protected]
+      - 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: Build docs website and API reference
+        env:
+          VERSION: ${{ inputs.version }}
+          ALIAS: ${{ inputs.alias }}
+        run: |
+          make release-docs VERSION="$VERSION" ALIAS="$ALIAS"
+          poetry run mike set-default --push latest
+      # Maintenance: Migrate to new gh-pages action
+      - name: Release API docs
+        uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # v3.8.0
+        env:
+          VERSION: ${{ inputs.version }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./api
+          keep_files: true
+          destination_dir: ${{ env.VERSION }}/api
+      - name: Release API docs to latest
+        if: ${{ inputs.alias == 'latest' }}
+        uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # v3.8.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./api
+          keep_files: true
+          destination_dir: latest/api