Skip to content

Commit 9100859

Browse files
kozubkozub
committed
docs: Add support for docs versioning and publishing docs to S3 with version. (#1239)
1 parent bca90c9 commit 9100859

File tree

5 files changed

+180
-47
lines changed

5 files changed

+180
-47
lines changed

‎.github/workflows/docs.yml

-41
This file was deleted.

‎.github/workflows/rebuild-latest-docs.yml

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Rebuild latest docs
2+
3+
# PROCESS
4+
#
5+
# 1. Build User Guide and API docs
6+
# 2. Publish to GitHub Pages
7+
# 3. Publish to S3 (new home)
8+
9+
# USAGE
10+
#
11+
# Only used for deploying a documentation hotfix to /latest and its associated version w/o a full release.
12+
#
13+
# Steps:
14+
#
15+
# 1. Trigger "Rebuild latest docs" workflow manually: https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow
16+
# 2. Use the latest version released under Releases e.g. 2.0.0
17+
18+
on:
19+
workflow_dispatch:
20+
inputs:
21+
latest_published_version:
22+
description: "Latest published version to rebuild latest docs for, e.g. 1.4.2"
23+
default: "1.4.2"
24+
required: true
25+
26+
permissions:
27+
contents: read
28+
29+
jobs:
30+
release-docs:
31+
permissions:
32+
contents: write # push to gh-pages
33+
pages: write # deploy gh-pages website
34+
id-token: write # trade JWT token for AWS credentials in AWS Docs account
35+
secrets: inherit
36+
uses: ./.github/workflows/reusable-publish-docs.yml
37+
with:
38+
version: ${{ inputs.latest_published_version }}
39+
alias: latest

‎.github/workflows/release-doc.yml

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: Docs
2+
3+
on:
4+
release:
5+
types:
6+
- published
7+
workflow_dispatch: {}
8+
9+
jobs:
10+
release-docs:
11+
permissions:
12+
contents: write
13+
pages: write
14+
id-token: write
15+
secrets: inherit
16+
uses: ./.github/workflows/reusable-publish-docs.yml
17+
with:
18+
version: main
19+
alias: stage

‎.github/workflows/reusable-publish-docs.yml

+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
name: Reusable Publish docs
2+
3+
env:
4+
BRANCH: main
5+
ORIGIN: aws-powertools/powertools-lambda-java
6+
VERSION: ""
7+
8+
on:
9+
workflow_call:
10+
inputs:
11+
version:
12+
description: "Version to build and publish docs (1.28.0, develop)"
13+
required: true
14+
type: string
15+
alias:
16+
description: "Alias to associate version (latest, stage)"
17+
required: true
18+
type: string
19+
detached_mode:
20+
description: "Whether it's running in git detached mode to ensure git is sync'd"
21+
required: false
22+
default: false
23+
type: boolean
24+
25+
permissions:
26+
contents: write
27+
id-token: write
28+
pages: write
29+
30+
jobs:
31+
publish-docs:
32+
runs-on: ubuntu-latest
33+
environment: Docs
34+
steps:
35+
- name: Checkout code
36+
uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
37+
with:
38+
# While `fetch-depth` is used to allow the workflow to later commit & push the changes.
39+
fetch-depth: 0
40+
- name: Set up Python
41+
uses: actions/setup-python@57ded4d7d5e986d7296eab16560982c6dd7c923b # v4.6.0
42+
with:
43+
python-version: "3.8"
44+
- name: Install doc generation dependencies
45+
run: |
46+
pip install --upgrade pip
47+
pip install -r docs/requirements.txt
48+
- name: Setup doc deploy
49+
run: |
50+
git config --global user.name Docs deploy
51+
git config --global user.email [email protected]
52+
- name: Git refresh tip (detached mode)
53+
# Git Detached mode (release notes) doesn't have origin
54+
if: ${{ inputs.detached_mode }}
55+
run: |
56+
git config pull.rebase true
57+
git config remote.origin.url >&- || git remote add origin https://github.com/"$ORIGIN"
58+
git pull origin "$BRANCH"
59+
- name: Normalize Version Number
60+
run: echo "VERSION=$(echo ${{ inputs.version }} | sed 's/v//')" >> $GITHUB_ENV
61+
- name: Build docs website and API reference
62+
env:
63+
ALIAS: ${{ inputs.alias }}
64+
run: |
65+
rm -rf site
66+
mkdocs build
67+
mike deploy --update-aliases --no-redirect ${{ env.VERSION }} ${{ env.ALIAS }} --branch backup-gh-pages
68+
# Set latest version as a default
69+
mike set-default latest --branch backup-gh-pages
70+
- name: Configure AWS credentials
71+
uses: aws-actions/configure-aws-credentials@e1e17a757e536f70e52b5a12b2e8d1d1c60e04ef # v2.0.0
72+
with:
73+
aws-region: us-east-1
74+
role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }}
75+
- name: Deploy Docs (Version)
76+
env:
77+
VERSION: ${{ inputs.version }}
78+
ALIAS: ${{ inputs.alias }}
79+
run: |
80+
aws s3 sync \
81+
site/ \
82+
s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.VERSION }}/
83+
- name: Deploy Docs (Alias)
84+
env:
85+
VERSION: ${{ inputs.version }}
86+
ALIAS: ${{ inputs.alias }}
87+
run: |
88+
aws s3 sync \
89+
site/ \
90+
s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.ALIAS }}/
91+
- name: Deploy Docs (Version JSON)
92+
env:
93+
VERSION: ${{ inputs.version }}
94+
ALIAS: ${{ inputs.alias }}
95+
96+
97+
# 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.
98+
# Instead, we're using some shell script that manages the versions.
99+
#
100+
# Operations:
101+
# 1. Download the versions.json file from S3
102+
# 2. Find any reference to the alias and delete it from the versions file
103+
# 3. This is voodoo (don't use JQ):
104+
# - we assign the input as $o and the new version/alias as $n,
105+
# - we check if the version number exists in the file already (for republishing docs)
106+
# - if it's an alias (stage/latest/*) or old version, we do nothing and output $o (original input)
107+
# - if it's a new version number, we add it at position 0 in the array.
108+
# 4. Once done, we'll upload it back to S3.
109+
110+
run: |
111+
aws s3 cp \
112+
s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json \
113+
versions_old.json
114+
jq 'del(.[].aliases[] | select(. == "${{ env.ALIAS }}"))' < versions_old.json > versions_proc.json
115+
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 == "${{ env.VERSION }}";.) then $o else $n + $o end' < versions_proc.json > versions.json
116+
aws s3 cp \
117+
versions.json \
118+
s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json

‎mkdocs.yml

+4-6
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,11 @@ nav:
1313
- Utilities:
1414
- utilities/idempotency.md
1515
- utilities/parameters.md
16-
- utilities/large_messages.md
16+
- utilities/sqs_large_message_handling.md
1717
- utilities/batch.md
1818
- utilities/validation.md
1919
- utilities/custom_resources.md
2020
- utilities/serialization.md
21-
- Deprecated:
22-
- utilities/sqs_large_message_handling.md
23-
- utilities/sqs_batch.md
24-
- Processes:
25-
- processes/maintainers.md
2621

2722
theme:
2823
name: material
@@ -87,6 +82,9 @@ extra_javascript:
8782
- javascript/extra.js
8883

8984
extra:
85+
version:
86+
provider: mike
87+
default: latest
9088
powertools:
9189
version: 1.16.1 # to update after each release (we do not want snapshot version here)
9290

0 commit comments

Comments
 (0)