docs: enable versioning feature (#374)

* feat(docs): enable docs versioning

* feat: update workflows to support docs versioning

* chore: update automated activities note

* chore: update to latest mkdocs-material

* chore: merge alias redirect in one step

* docs: add 404 redirect for old docs

* chore: add docs redirect on deploy

Signed-off-by: heitorlessa <lessa@amazon.co.uk>

* chore: enable versioned api ref

Signed-off-by: heitorlessa <lessa@amazon.co.uk>

Author: heitorlessa

.github/workflows/publish.yml

@@ -21,16 +21,19 @@ name: Publish to PyPi
 # 7. Kick off Lambda Layer pipeline to publish latest version with extra dependencies as a SAR App
 # 8. Builds a fresh version of docs including Changelog updates
 # 9. Push latest release source code to master using release title as the commit message
+# 10. Builds latest documentation for new release, and update latest alias pointing to the new release tag
 
 on:
   release:
     types: [published]
 
 jobs:
-  upload:
+  release:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
     - name: Set up Python
       uses: actions/setup-python@v1
       with:
@@ -68,8 +71,21 @@ jobs:
         AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
         AWS_DEFAULT_REGION: eu-west-1
         AWS_DEFAULT_OUTPUT: json
-
-
+    - name: Setup doc deploy
+      run: |
+        git config --global user.name Docs deploy
+        git config --global user.email docs@dummy.bot.com
+    - 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: Deploy all docs
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./api
+        keep_files: true
+        destination_dir: ${{ env.RELEASE_TAG_VERSION }}/api
 
   sync_master:
     needs: upload

.github/workflows/python_docs.yml

@@ -1,59 +1,41 @@
 name: Docs
 
 on:
-  pull_request:
-    branches:
-      - master
   push:
     branches:
-      - master
-      - docs/mkdocs
-      # Disabled until docs support versioning per branch/release
-      # - develop
-  release:
-    types: [published] # update Docs upon new release
+      - develop
 
 jobs:
-  api-docs:
+  docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
       - name: Set up Python
         uses: actions/setup-python@v1
         with:
           python-version: "3.8"
-      - uses: actions/setup-node@v1
-        with:
-          node-version: '12'
-      - name: Capture branch and tag
-        id: branch_name
+      - name: Install dependencies
+        run: make dev
+      - name: Setup doc deploy
         run: |
-          echo "SOURCE_BRANCH=${GITHUB_REF#refs/heads/}" >> $GITHUB_ENV
-          echo "SOURCE_TAG=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
-      - name: Build docs website
-        run: make build-docs-website
-      - name: Build docs API reference
-        # if: env.SOURCE_BRANCH == 'master' # Disabled until docs support versioning per branch/release
-        run: make build-docs-api
+          git config --global user.name Docs deploy
+          git config --global user.email docs@dummy.bot.com
+      - name: Build docs website and API reference
+        run: make release-docs VERSION="develop" ALIAS="stage"
       - name: Deploy all docs
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./dist
-
-      # Disabled until docs support versioning per branch/release
-      # - name: Deploy docs website
-      #   uses: peaceiris/actions-gh-pages@v3
-      #   with:
-      #     github_token: ${{ secrets.GITHUB_TOKEN }}
-      #     publish_dir: ./dist
-      #     # when deploying docs website only
-      #     # we need to keep existing API docs checked in
-      #     # but only for dev branch
-      #     keep_files: true
-      # - name: Deploy all docs
-      #   uses: peaceiris/actions-gh-pages@v3
-      #   if: env.SOURCE_BRANCH == 'master'
-      #   with:
-      #     github_token: ${{ secrets.GITHUB_TOKEN }}
-      #     publish_dir: ./dist
+          publish_dir: ./api
+          keep_files: true
+          destination_dir: develop/api
+      - 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

.gitignore

@@ -300,3 +300,6 @@ wheelhouse
 docs/.cache/
 docs/public
 node_modules
+api/
+site/
+!404.html

404.html

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <script>
+        const websitePath = window.location.pathname;
+        const versionRegex = /(\w.+)\/(latest|([0-9]+)\.([0-9]+)\.([0-9]+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+)?)/;
+
+        if (websitePath.search(versionRegex) === -1) {
+            let projectName = "aws-lambda-powertools-python"
+            // redirect old links to latest version alias
+            window.location = websitePath.replace(projectName, `${projectName}/latest`)
+        }
+    </script>
+</head>
+
+</html>

Makefile

@@ -31,20 +31,18 @@ pr: lint pre-commit test security-baseline complexity-baseline
 build: pr
 	poetry build
 
-build-docs:
-	@$(MAKE) build-docs-website
+release-docs:
+	@echo "Rebuilding docs"
+	rm -rf site api
+	@echo "Updating website docs"
+	poetry run mike deploy --push --update-aliases ${VERSION} ${ALIAS}
+	@echo "Building API docs"
 	@$(MAKE) build-docs-api
 
-build-docs-api: dev
-	mkdir -p dist/api
-	poetry run pdoc --html --output-dir dist/api/ ./aws_lambda_powertools --force
-	mv -f dist/api/aws_lambda_powertools/* dist/api/
-	rm -rf dist/api/aws_lambda_powertools
-
-build-docs-website: dev
-	mkdir -p dist
-	poetry run mkdocs build
-	cp -R site/* dist/
+build-docs-api:
+	poetry run pdoc --html --output-dir ./api/ ./aws_lambda_powertools --force
+	mv -f ./api/aws_lambda_powertools/* ./api/
+	rm -rf ./api/aws_lambda_powertools
 
 docs-local:
 	poetry run mkdocs serve

mkdocs.yml

@@ -1,10 +1,13 @@
 site_name: Lambda Powertools Python
 site_description: AWS Lambda Powertools for Python
 site_author: Amazon Web Services
+repo_url: https://github.com/awslabs/aws-lambda-powertools-python
+edit_uri: edit/develop/docs
+
 nav:
   - Homepage: index.md
   - Changelog: changelog.md
-  - API reference: https://awslabs.github.io/aws-lambda-powertools-python/api/" target="_blank
+  - API reference: api/" target="_blank
   - Core utilities:
       - core/tracer.md
       - core/logger.md
@@ -62,6 +65,6 @@ extra_javascript:
   - javascript/aws-amplify.min.js
   - javascript/extra.js
 
-
-repo_url: https://github.com/awslabs/aws-lambda-powertools-python
-edit_uri: edit/develop/docs
+extras:
+  version:
+    provider: mike

poetry.lock

@@ -52,6 +52,7 @@ flake8-eradicate = "^1.0.0"
 flake8-bugbear = "^21.3.2"
 mkdocs-material = "^7.0.6"
 mkdocs-git-revision-date-plugin = "^0.3.1"
+mike = "^0.6.0"
 
 
 [tool.poetry.extras]