The setup I use for keeping documentation websites up to date with new releases for all of my open source packages, using GitHub Actions and AWS.
YouTube: https://www.youtube.com/watch?v=TRTTOc25PWs
Transcript
Here’s the automated docs website deployment mechanism that I’ve got set up for all of my open source packages. That’s Yulin, PinyinJS, Colophon, Part Factory and Smartass.
We’ll take Yulin as an example. Here’s a PR for a new feature in Yulin, which is simulated CloudFront Key Value Stores. This is quite a big PR, probably too big, but one of the things that’s included on the PR is this documentation update.
This is the documentation for simulated CloudFront, and this is going to end up on the documentation website for Yulin after we’ve merged this new feature and released it.
If I come back to the PR conversation, we can squash and merge, and the branch gets deleted automatically by GitHub.
Now we can go into the Actions in the main Yulin repo, and we can come to the release action. We click over here on run workflow and we’re going to run a release on the main branch. As this is a new feature, it can be a minor version, so I will enable that and we’ll click run workflow.
This is the release workflow for the main Yulin repo. This is going to build the latest main of Yulin, lint it and test it, and create a release, both as a tag in GitHub and also as a publish to npm. This takes a couple of minutes, so I’ll speed up the video.
That’s finished releasing, and what that has done is created a new release tagged in GitHub as version 1.11.0. It’s also published it to npm, 1.11.0, published a few seconds ago.
In terms of the main Yulin repo and package, that’s all done. Version 1.11.0 is now available. But we’ve also got the documentation website on yulinsim.dev. We need to get that deployed as well for the new version.
This is the repo for the documentation website, and we’ve got a couple of workflows here to help automate that. The first one is Sync docs here. I’ll trigger that. This checks for a new release in the main repo, and if there is a new release, it will create a PR with the updated documentation website.
That’s done. We should now have this PR, so we can have a look at that. Note that the documentation website also contains plain text documentation for LLMs to read, just to save on token usage. We can see we’ve got the documentation for the new simulated CloudFront Key Value Store feature.
Coming back to the PR conversation, because this was an automated PR, we have to approve the workflows to run against it. I’ve done that, and we can enable auto-merge on this one. That’s done, automatically merged and the branch gets deleted.
There is another GitHub Actions workflow that triggers on merges to the main branch in this documentation website repo. That’s automatically kicked off because we just merged the documentation update to main. We can have a look at this one. This is now deploying our updated documentation website to AWS.
The reason it takes several minutes is because it does a full upload of every file in the documentation website to S3. That has now completed.
If we come back to our documentation website and we do a refresh of the page, we can see it says documenting Yulin version 1.11.0. Coming back to the documentation itself, we can search for Key Value Store. Now we’re seeing simulated CloudFront Key Value Store, and we can click straight through to that part of the documentation. Here it is in the sidebar, Key Value Store. There’s the documentation for our new Key Value Store feature in simulated CloudFront.
A lot of the process to get that released and get the documentation website updated is automated. There are some manual approval steps in there. That’s because personally, I don’t really like the idea of machines just going ahead and releasing and deploying things without sign off by a human being.
