aws-powertools
Maintenance: Version the documentation
Summary
Currently the documentation is not versioned, unlike Python and Typescript. We should version the doc to be consistent with other runtimes and to prepare for v2.
Why is this needed?
- Consistency with other runtimes
- Keep history of changes (doc for a specified version)
- Preparing v2 (we'll need to have both v1 and v2 available at least)
Which area does this relate to?
Automation, Governance
Solution
See how python is doing: https://github.com/aws-powertools/powertools-lambda-python/blob/develop/.github/workflows/reusable_publish_docs.yml. Check with @sthulb / @heitorlessa.
Acknowledgment
- [X] This request meets Powertools for AWS Lambda (Java) Tenets
- [ ] Should this be considered in other Powertools for AWS Lambda (Java) languages? i.e. Python, TypeScript
Python/TS uses a python package called mike to version docs – but in our post GH Pages world, we might want to look into doing this differently.
Ok so I've been taking a look at this and I have a proposal.
From an MkDocs standpoint, all we need to do to enable the versioning is to add these lines in the mkdocs.yml file under extra:
extra:
version:
provider: mike
default: latest # the is the alias we want to be the main
Whenever this is enabled, MkDocs will try to load a versions.json file from the root of the static site, if present it'll use it to render a dropdown with the versions at the top of the site:
The versions.json file should have a structure like the one below, and despipe MkDocs thinking it's built using mike, it can be built manually. We know this works because we've ditched mike over a year ago in TypeScript and Python and still have versioning.
[
{
"title": "2 (preview)",
"version": "2.x",
"aliases": [
"latest"
]
},
{
"title": "legacy",
"version": "1.x",
"aliases": []
}
]
For this to work however we'll also need to make a few actions in our backend, specifically:
1 Check if CloudFront distribution has special rewrites for Java, if so make it work like Python/TS so it supports versions
2 Manually update S3 bucket folder structure to accommodate versions
3 Update CI (build-docs.yml) to publish new versions to the correct folder
Regarding number 2, I'm assuming that the current structure of the docs in S3 looks something like this lambda-java/<content>.
If this is the case, we'll have to create a new level of directories - one for each version - and move <content> under 1.x so it looks like:
-
lambda-java/1.x/<content> -
lambda-java/2.x/<new content> -
lambda-java/versions.json
Regarding number 3, we'll have to update the workflow so that it publishes new v2 versions in the corresponding directory. For now we'll continue to work as we do today, meaning each new build replaces the previous one. We won't be introducing full docs versioning at this time.
We also might need to revert somme changes to the base url in the mkdocs.yml config file, since now we'll have a single base url for both versions. Finally, we can also add an override like this one that informs customers they're not looking at the latest version when they're navigating the legacy docs.
