Port shotover docs/website to github actions

[rukai]

hosting

We are moving the hosting from netlify to github pages.

Possibly we would want to host the docs and marketing parts of the websites on different github pages:

• docs.shotover.io directs to the github pages of this repo.
• shotover.io directs to the github pages of another repo.

However I'm worried about complications due to needing to pay for hosting separately for these repos. So in this design I'm going to go ahead with hosting it all in this github pages, but there will be a separate repo with the website for two reasons:

• avoiding increasing the size of this repo with all the image assets and what not.
• allowing for iteration on the project seperately, front end people can contribute without going through the process of regular shotover work.

To achieve this with one hosted repo, on every commit to shotover we will clone from the shotover-website repo, build it and deploy to the root of the github pages branch.

pages

• shotover.io/index.html contains all the marketing
• shotover.io/docs/vx.y/ exists for every breaking version of shotover released
  • e.g. v0.5, v0.6, v1, v2
  • non-breaking releases overwrite the previous release e.g. v0.5.1 replaces v0.5
• shotover.io/docs/latest/ contains docs for the latest released version
• shotover.io/docs/main/ contains docs for the latest main version
• shotover.io/docs/index.html contains links to all docs versions + latest (but not main which remains unlisted)

Alter github actions release workflow to run mdbook and include the contents in latest and the current vx.y directory.

Downsides:

• no links between versions since mdbook is not aware of the versioning.
  • If there is a mdbook like tool that does support versioning we should consider it.
• No way to regenerate documentation for versions of shotover released before this system was in place
  • I dont think shotover is big enough yet for this to be a problem.
• We will lose the custom styling and header currently used on the documentation pages of shotover.io
  • I'm personally not fussed about this, it ensures that what we see locally with mdbook is what we will get when deployed.

Implementation Chunking

1. Add new workflow publish-main-to-pages.yaml to run on every merged PR to:
   • generate mdbook docs at the shotover repo github pages at /docs/main
   • the purpose of this is to allow us to preview the website before changes reach a release.
   • this also immediately gives us a way to view current docs before we even transfer the domain over.
2. Alter release workflow to:
   • generate mdbook docs at the shotover repo github pages at /docs/latest
   • generate index.html linking to latest
3. Add new stage to publish-main-to-pages.yaml to:
   • Clone the shotover website at a hardcoded commit and publish to /
   • This should be a minimum implementation at which point we could swap the website over to it.
4. Add logic to release workflow to release to /docs/vx.y as well as latest.
   • Will need logic to convert current version string to one of the form v0.y/vx, completely clear current directory and write new docs.

[rukai]

Turns out I misremembered and github pages does not support a way to update portions of a deployed "github pages" while keeping the rest untouched. We can keep the same layout but will need to redeploy all versions every commit. This should be doable as regenerating a version should be pretty fast.

new chunking

1. Add new workflow publish-website.yaml to run on every merged PR to:
   • generate mdbook docs at the shotover repo github pages at /docs/main
   • this immediately gives us a way to view current docs before we even transfer the domain over.
2. Alter workflow to:
   • checkout latest tag (query for highest vx.y.z tag) and then generate mdbook docs at /docs/latest
   • generate index.html linking to latest
3. Alter workflow to:
   • Clone the shotover website at a hardcoded commit and publish to /
   • This should be a minimum implementation at which point we could swap the website over to it.
4. Alter workflow to:
   • Add logic to release workflow to release to /docs/vx.y as well as latest.
   • Will need logic to iterate over all vx.y.z tags and then find the highest version of each breaking release and deploy as v0.y/vx