Skip to content

Commit da3aa5d

Browse files
heitorlessaheitorlessa
authored
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 <[email protected]> * chore: enable versioned api ref Signed-off-by: heitorlessa <[email protected]>
1 parent b558b18 commit da3aa5d

File tree

8 files changed

+165
-60
lines changed

8 files changed

+165
-60
lines changed

Diff for: ‎.github/workflows/publish.yml

+19-3
Original file line numberDiff line numberDiff line change
@@ -21,16 +21,19 @@ name: Publish to PyPi
2121
# 7. Kick off Lambda Layer pipeline to publish latest version with extra dependencies as a SAR App
2222
# 8. Builds a fresh version of docs including Changelog updates
2323
# 9. Push latest release source code to master using release title as the commit message
24+
# 10. Builds latest documentation for new release, and update latest alias pointing to the new release tag
2425

2526
on:
2627
release:
2728
types: [published]
2829

2930
jobs:
30-
upload:
31+
release:
3132
runs-on: ubuntu-latest
3233
steps:
3334
- uses: actions/checkout@v2
35+
with:
36+
fetch-depth: 0
3437
- name: Set up Python
3538
uses: actions/setup-python@v1
3639
with:
@@ -68,8 +71,21 @@ jobs:
6871
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
6972
AWS_DEFAULT_REGION: eu-west-1
7073
AWS_DEFAULT_OUTPUT: json
71-
72-
74+
- name: Setup doc deploy
75+
run: |
76+
git config --global user.name Docs deploy
77+
git config --global user.email [email protected]
78+
- name: Build docs website and API reference
79+
run: |
80+
make release-docs VERSION=${RELEASE_TAG_VERSION} ALIAS="latest"
81+
poetry run mike set-default --push latest
82+
- name: Deploy all docs
83+
uses: peaceiris/actions-gh-pages@v3
84+
with:
85+
github_token: ${{ secrets.GITHUB_TOKEN }}
86+
publish_dir: ./api
87+
keep_files: true
88+
destination_dir: ${{ env.RELEASE_TAG_VERSION }}/api
7389

7490
sync_master:
7591
needs: upload

Diff for: ‎.github/workflows/python_docs.yml

+23-41
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,41 @@
11
name: Docs
22

33
on:
4-
pull_request:
5-
branches:
6-
- master
74
push:
85
branches:
9-
- master
10-
- docs/mkdocs
11-
# Disabled until docs support versioning per branch/release
12-
# - develop
13-
release:
14-
types: [published] # update Docs upon new release
6+
- develop
157

168
jobs:
17-
api-docs:
9+
docs:
1810
runs-on: ubuntu-latest
1911
steps:
20-
- uses: actions/checkout@v1
12+
- uses: actions/checkout@v2
13+
with:
14+
fetch-depth: 0
2115
- name: Set up Python
2216
uses: actions/setup-python@v1
2317
with:
2418
python-version: "3.8"
25-
- uses: actions/setup-node@v1
26-
with:
27-
node-version: '12'
28-
- name: Capture branch and tag
29-
id: branch_name
19+
- name: Install dependencies
20+
run: make dev
21+
- name: Setup doc deploy
3022
run: |
31-
echo "SOURCE_BRANCH=${GITHUB_REF#refs/heads/}" >> $GITHUB_ENV
32-
echo "SOURCE_TAG=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
33-
- name: Build docs website
34-
run: make build-docs-website
35-
- name: Build docs API reference
36-
# if: env.SOURCE_BRANCH == 'master' # Disabled until docs support versioning per branch/release
37-
run: make build-docs-api
23+
git config --global user.name Docs deploy
24+
git config --global user.email [email protected]
25+
- name: Build docs website and API reference
26+
run: make release-docs VERSION="develop" ALIAS="stage"
3827
- name: Deploy all docs
3928
uses: peaceiris/actions-gh-pages@v3
4029
with:
4130
github_token: ${{ secrets.GITHUB_TOKEN }}
42-
publish_dir: ./dist
43-
44-
# Disabled until docs support versioning per branch/release
45-
# - name: Deploy docs website
46-
# uses: peaceiris/actions-gh-pages@v3
47-
# with:
48-
# github_token: ${{ secrets.GITHUB_TOKEN }}
49-
# publish_dir: ./dist
50-
# # when deploying docs website only
51-
# # we need to keep existing API docs checked in
52-
# # but only for dev branch
53-
# keep_files: true
54-
# - name: Deploy all docs
55-
# uses: peaceiris/actions-gh-pages@v3
56-
# if: env.SOURCE_BRANCH == 'master'
57-
# with:
58-
# github_token: ${{ secrets.GITHUB_TOKEN }}
59-
# publish_dir: ./dist
31+
publish_dir: ./api
32+
keep_files: true
33+
destination_dir: develop/api
34+
- name: Create redirect from old docs
35+
run: |
36+
git checkout gh-pages
37+
test -f 404.html && echo "Redirect already set" && exit 0
38+
git checkout develop -- 404.html
39+
git add 404.html
40+
git commit -m "chore: set docs redirect" --no-verify
41+
git push origin gh-pages -f

Diff for: ‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -300,3 +300,6 @@ wheelhouse
300300
docs/.cache/
301301
docs/public
302302
node_modules
303+
api/
304+
site/
305+
!404.html

Diff for: ‎404.html

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
4+
<head>
5+
<meta charset="UTF-8">
6+
<meta http-equiv="X-UA-Compatible" content="IE=edge">
7+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
8+
<script>
9+
const websitePath = window.location.pathname;
10+
const versionRegex = /(\w.+)\/(latest|([0-9]+)\.([0-9]+)\.([0-9]+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+)?)/;
11+
12+
if (websitePath.search(versionRegex) === -1) {
13+
let projectName = "aws-lambda-powertools-python"
14+
// redirect old links to latest version alias
15+
window.location = websitePath.replace(projectName, `${projectName}/latest`)
16+
}
17+
</script>
18+
</head>
19+
20+
</html>

Diff for: ‎Makefile

+10-12
Original file line numberDiff line numberDiff line change
@@ -31,20 +31,18 @@ pr: lint pre-commit test security-baseline complexity-baseline
3131
build: pr
3232
poetry build
3333

34-
build-docs:
35-
@$(MAKE) build-docs-website
34+
release-docs:
35+
@echo "Rebuilding docs"
36+
rm -rf site api
37+
@echo "Updating website docs"
38+
poetry run mike deploy --push --update-aliases ${VERSION} ${ALIAS}
39+
@echo "Building API docs"
3640
@$(MAKE) build-docs-api
3741

38-
build-docs-api: dev
39-
mkdir -p dist/api
40-
poetry run pdoc --html --output-dir dist/api/ ./aws_lambda_powertools --force
41-
mv -f dist/api/aws_lambda_powertools/* dist/api/
42-
rm -rf dist/api/aws_lambda_powertools
43-
44-
build-docs-website: dev
45-
mkdir -p dist
46-
poetry run mkdocs build
47-
cp -R site/* dist/
42+
build-docs-api:
43+
poetry run pdoc --html --output-dir ./api/ ./aws_lambda_powertools --force
44+
mv -f ./api/aws_lambda_powertools/* ./api/
45+
rm -rf ./api/aws_lambda_powertools
4846

4947
docs-local:
5048
poetry run mkdocs serve

Diff for: ‎mkdocs.yml

+7-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
site_name: Lambda Powertools Python
22
site_description: AWS Lambda Powertools for Python
33
site_author: Amazon Web Services
4+
repo_url: https://github.com/awslabs/aws-lambda-powertools-python
5+
edit_uri: edit/develop/docs
6+
47
nav:
58
- Homepage: index.md
69
- Changelog: changelog.md
7-
- API reference: https://awslabs.github.io/aws-lambda-powertools-python/api/" target="_blank
10+
- API reference: api/" target="_blank
811
- Core utilities:
912
- core/tracer.md
1013
- core/logger.md
@@ -62,6 +65,6 @@ extra_javascript:
6265
- javascript/aws-amplify.min.js
6366
- javascript/extra.js
6467

65-
66-
repo_url: https://github.com/awslabs/aws-lambda-powertools-python
67-
edit_uri: edit/develop/docs
68+
extras:
69+
version:
70+
provider: mike

Diff for: ‎poetry.lock

+82
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Diff for: ‎pyproject.toml

+1
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ flake8-eradicate = "^1.0.0"
5252
flake8-bugbear = "^21.3.2"
5353
mkdocs-material = "^7.0.6"
5454
mkdocs-git-revision-date-plugin = "^0.3.1"
55+
mike = "^0.6.0"
5556

5657

5758
[tool.poetry.extras]

0 commit comments

Comments
 (0)