Skip to content

Commit 871a844

Browse files
phipagphipag
authored
docs: Version documentation (#1878)
* Add versioning plugin for docs and update workflows. * Add old version banner override. Remove preview wording.
1 parent 9616520 commit 871a844

File tree

5 files changed

+106
-42
lines changed

5 files changed

+106
-42
lines changed

‎.github/workflows/build-docs.yml

Lines changed: 47 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
# Build Docs
1+
# Build Latest Docs
22
#
33
# Description:
4-
# Builds the docs and stores them in S3 to be served by our docs platform
4+
# Builds the latest docs and stores them in S3 to be served by our docs platform
55
#
66
# The workflow allows us to build to the main location (/lambda/java/) and to an alias
77
# (i.e. /lambda/java/preview/) if needed
@@ -15,17 +15,13 @@
1515
on:
1616
workflow_dispatch:
1717
inputs:
18-
alias:
18+
version:
19+
description: "Version to build and publish docs (1.28.0, develop)"
20+
required: true
1921
type: string
20-
required: false
21-
description: |
22-
Alias to deploy the documentation into, this is mostly for testing pre-release
23-
versions of the documentation, such as beta versions or snapshots.
2422

25-
https://docs.powertools.aws.dev/lambda/java/<alias>
26-
27-
name: Build Docs
28-
run-name: Build Docs - ${{ contains(github.head_ref, 'main') && 'main' || inputs.alias }}
23+
name: Build Latest Docs
24+
run-name: Build Latest Docs - ${{ inputs.version }}
2925

3026
jobs:
3127
docs:
@@ -35,28 +31,58 @@ jobs:
3531
id-token: write
3632
environment: Docs
3733
steps:
38-
- name: Sanity Check
39-
if: ${{ github.head_ref != 'main' || inputs.alias == '' }}
40-
run:
41-
echo "::error::No buildable docs"
42-
4334
- name: Checkout Repository
4435
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
45-
with:
36+
with:
4637
fetch-depth: 0
4738
- name: Build
4839
run: |
4940
mkdir -p dist
5041
docker build -t squidfunk/mkdocs-material ./docs/
5142
docker run --rm -t -v ${PWD}:/docs squidfunk/mkdocs-material build
52-
cp -R site/* dist/
5343
- name: Configure AWS credentials
5444
uses: aws-actions/configure-aws-credentials@ececac1a45f3b08a01d2dd070d28d111c5fe6722
5545
with:
5646
aws-region: us-east-1
5747
role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }}
58-
- name: Deploy
48+
- name: Deploy Docs (Version)
49+
env:
50+
VERSION: ${{ inputs.version }}
51+
ALIAS: "latest"
5952
run: |
6053
aws s3 sync \
61-
dist \
62-
s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ github.head_ref == 'main' && '' || format('{0}/', inputs.alias )}}
54+
site/ \
55+
s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.VERSION }}/
56+
- name: Deploy Docs (Alias)
57+
env:
58+
VERSION: ${{ inputs.version }}
59+
ALIAS: "latest"
60+
run: |
61+
aws s3 sync \
62+
site/ \
63+
s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.ALIAS }}/
64+
- name: Deploy Docs (Version JSON)
65+
env:
66+
VERSION: ${{ inputs.version }}
67+
ALIAS: "latest"
68+
# 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.
69+
# Instead, we're using some shell script that manages the versions.
70+
#
71+
# Operations:
72+
# 1. Download the versions.json file from S3
73+
# 2. Find any reference to the alias and delete it from the versions file
74+
# 3. This is voodoo (don't use JQ):
75+
# - we assign the input as $o and the new version/alias as $n,
76+
# - we check if the version number exists in the file already (for republishing docs)
77+
# - if it's an alias (stage/latest/*) or old version, we do nothing and output $o (original input)
78+
# - if it's a new version number, we add it at position 0 in the array.
79+
# 4. Once done, we'll upload it back to S3.
80+
run: |
81+
aws s3 cp \
82+
s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json \
83+
versions_old.json
84+
jq 'del(.[].aliases[] | select(. == "${{ env.ALIAS }}"))' < versions_old.json > versions_proc.json
85+
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
86+
aws s3 cp \
87+
versions.json \
88+
s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json

‎.github/workflows/release.yml

Lines changed: 45 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
#
2121
# Triggers:
2222
# - workflow_dispatch
23-
#
23+
#
2424
# Secrets:
2525
# - RELEASE.GPG_SIGNING_KEY
2626
# - RELEASE.OSSRH_JIRA_USERNAME
@@ -39,23 +39,23 @@ on:
3939
type: boolean
4040
description: Create snapshot release
4141
default: false
42-
skip_checks:
42+
skip_checks:
4343
type: boolean
4444
description: Skip quality checks
4545
default: false
4646
skip_publish:
4747
type: boolean
4848
description: Skip publish to Maven Central
4949
default: false
50-
continue_on_error:
50+
continue_on_error:
5151
type: boolean
5252
description: Continue to build if there's an error in quality checks
5353
default: false
5454

5555
name: Release
5656
run-name: Release – ${{ inputs.version }}
5757

58-
permissions:
58+
permissions:
5959
contents: read
6060

6161
env:
@@ -124,7 +124,7 @@ jobs:
124124

125125
quality:
126126
runs-on: ubuntu-latest
127-
needs:
127+
needs:
128128
- version_seal
129129
if: ${{ inputs.skip_checks == false }}
130130
permissions:
@@ -211,7 +211,7 @@ jobs:
211211
MAVEN_USERNAME: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
212212
MAVEN_PASSWORD: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}
213213
GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
214-
214+
215215
create_pr:
216216
runs-on: ubuntu-latest
217217
if: ${{ inputs.snapshot == false && always() && !contains(needs.*.result, 'failure') && !contains(needs.*.result, 'cancelled') }}
@@ -278,14 +278,49 @@ jobs:
278278
mkdir -p dist
279279
docker build -t squidfunk/mkdocs-material ./docs/
280280
docker run --rm -t -v ${PWD}:/docs squidfunk/mkdocs-material build
281-
cp -R site/* dist/
282281
- name: Configure AWS credentials
283282
uses: aws-actions/configure-aws-credentials@ececac1a45f3b08a01d2dd070d28d111c5fe6722
284283
with:
285284
aws-region: us-east-1
286285
role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }}
287-
- name: Deploy
286+
- name: Deploy Docs (Version)
287+
env:
288+
VERSION: ${{ inputs.version }}
289+
ALIAS: 'latest'
288290
run: |
289291
aws s3 sync \
290-
dist \
291-
s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ inputs.version }}/
292+
site/ \
293+
s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.VERSION }}/
294+
- name: Deploy Docs (Alias)
295+
env:
296+
VERSION: ${{ inputs.version }}
297+
ALIAS: 'latest'
298+
run: |
299+
aws s3 sync \
300+
site/ \
301+
s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/${{ env.ALIAS }}/
302+
- name: Deploy Docs (Version JSON)
303+
env:
304+
VERSION: ${{ inputs.version }}
305+
ALIAS: 'latest'
306+
# 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.
307+
# Instead, we're using some shell script that manages the versions.
308+
#
309+
# Operations:
310+
# 1. Download the versions.json file from S3
311+
# 2. Find any reference to the alias and delete it from the versions file
312+
# 3. This is voodoo (don't use JQ):
313+
# - we assign the input as $o and the new version/alias as $n,
314+
# - we check if the version number exists in the file already (for republishing docs)
315+
# - if it's an alias (stage/latest/*) or old version, we do nothing and output $o (original input)
316+
# - if it's a new version number, we add it at position 0 in the array.
317+
# 4. Once done, we'll upload it back to S3.
318+
run: |
319+
aws s3 cp \
320+
s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json \
321+
versions_old.json
322+
jq 'del(.[].aliases[] | select(. == "${{ env.ALIAS }}"))' < versions_old.json > versions_proc.json
323+
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
324+
aws s3 cp \
325+
versions.json \
326+
s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-java/versions.json

‎docs/index.md

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,6 @@ title: Homepage
33
description: Powertools for AWS Lambda (Java)
44
---
55

6-
![aws provider](https://img.shields.io/badge/provider-AWS-orange?logo=amazon-aws&color=ff9900) ![Build status](https://github.com/aws-powertools/powertools-lambda-java/actions/workflows/publish-v2-snapshot.yml/badge.svg) ![Maven Central](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Faws.oss.sonatype.org%2Fcontent%2Frepositories%2Fsnapshots%2Fsoftware%2Famazon%2Flambda%2Fpowertools-parent%2Fmaven-metadata.xml
7-
)
8-
9-
???+ warning
10-
You are browsing the documentation for Powertools for AWS Lambda (Java) - v2. This is a snapshot release and not stable!
11-
Check out our stable [v1](https://docs.powertools.aws.dev/lambda/java/) documentation if this is not what you wanted.
12-
The v2 maven snapshot repository can be found [here](https://aws.oss.sonatype.org/content/repositories/snapshots/software/amazon/lambda/) .
13-
146
Powertools for AWS Lambda (Java) is a suite of utilities for AWS Lambda Functions that makes tracing with AWS X-Ray, structured logging and creating custom metrics asynchronously easier.
157

168
???+ tip

‎docs/overrides/main.html

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{% extends "base.html" %}
2+
3+
{% block outdated %}
4+
You're not viewing the latest version.
5+
<a href="{{ '../' ~ base_url }}">
6+
<strong>Click here to go to latest.</strong>
7+
</a>
8+
{% endblock %}

‎mkdocs.yml

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
site_name: Powertools for AWS Lambda (Java) Preview
2-
site_description: Powertools for AWS Lambda (Java) Preview
1+
site_name: Powertools for AWS Lambda (Java)
2+
site_description: Powertools for AWS Lambda (Java)
33
site_author: Amazon Web Services
4-
site_url: https://docs.powertools.aws.dev/lambda/java/preview/
4+
site_url: https://docs.powertools.aws.dev/lambda/java/
55
nav:
66
- Homepage: index.md
77
- Changelog: changelog.md
@@ -119,6 +119,9 @@ extra_javascript:
119119
extra:
120120
powertools:
121121
version: 2.0.0
122+
version:
123+
provider: mike
124+
default: latest
122125

123126
repo_url: https://github.com/aws-powertools/powertools-lambda-java
124127
edit_uri: edit/main/docs

0 commit comments

Comments
 (0)