Serve multiple rendered HTML specification versions from gh-pages branch

[ml-evs]

Now #378 is merged, I would like to go through and manually update the gh pages branch to include HTML builds of our old spec versions (potentially with minor tweaks required that faithfully represent the old specs).

The idea would then be to set up the CI so that:

• pushes to develop trigger a build that replaces the develop version of the spec
• releases trigger a build that replaces a specific built tag of the spec
• this should probably be set up before we next release, to avoid needing to make any spurious changes after the fact.

I will probably nuke the gh_pages branch before doing this, then restrict push access to it.

The beauty of a divergent gh pages branch is that we could make any edits to the built versions (say we wanted to tweak the style sheet or template to include banner redirects to the latest version) we wanted directly to that, without needing PRs to develop.

[ml-evs]

Just made a manual start on this on the gh-pages branch, so the development spec is now at https://www.optimade.org/OPTIMADE/specification/develop/

We can decide what the best canonical URLs are at some point. I'll try to make a PR to develop here that updates the workflow to automtically include any future releases or changes to develop (although maybe this is infrequent enough that we could juts keep develop up to date and manually add releases...) Will need to design some kind of splash page for gh-pages too

[ml-evs]

We could also consider building and hosting PR previews.

[ml-evs]

Hmm, I thought I had commented here with plans for the specification repo, but I guess it never hit send... I see @rartino has started the work already at https://github.com/Materials-Consortia/specification. For now @rartino, shall I just duplicate the gh pages in the this repo to there and then get the links set up correctly? I think going forward, we could either use an indirect workflow call to call the build in that repo, or simply build here and push to the spec repo with a bot account.

[rartino]

Right; when I didn't see any answer or repo, I thought I'd do a quick experiment with a setup. The current specification repo works, in that it renders the OPTIMADE "default branch" specification to https://www.optimade.org/specification when the "Build OPTIMADE specification" gets triggered, which right now only is done manually by going here:

https://github.com/Materials-Consortia/specification/actions/workflows/pages.yml

and clicking the "run workflow" button. If we are happy with this we need to decide how to trigger those builds. There are a couple of possible strategies: just build it every day (may be optimized to skip out early if nothing has changed); have the main repo push something to the specification repo (e.g., a submodule reference with the state of the repo); or let the main repo build the pages and push them into the repo. (Or if someone has an even better idea.)

I think I slightly prefer the idea of just doing periodic builds to minimize the complexity in repo dependencies (handling secretes, etc.) which can go wrong and no one will know how to fix it.

While this is a nice way to get the spec published at a nice (and https-valid) URL, I realized that we anyway may want to keep the build in the OPTIMADE repo and set it up "on PR" to enable rendered previews of PRs. Those don't need nice URL:s though.