Use mike to versionise the website.

[gouttegd]

Resolves [#530]

• docs/ have been added/updated if necessary
• make test has been run locally
• tests have been added/updated (if applicable)
• CHANGELOG.md has been updated.

This PR configures MkDocs to use mike in order to create a fully versionised website.

Edit: Forget what’s below, unless you want for some reason to test the entire procedure for yourself. Go directly to that comment if you just want to see what the result would look like.

Full procedure for generating the versionised website for testing:

To test the result:

1. Make sure you have the gh-pages branch locally tracked in your local repo. If not:

$ git branch -t gh-pages origin/gh-pages

2. Create a tag on the gh-pages branch (so that you can easily revert all the changes you’ll have to do on that branch in order to test the versionised website):

$ git tag savepoint gh-pages

3. Checkout the branch corresponding to this PR:

$ git branch -t versionise-entire-website origin/versionise-entire-website
$ git checkout versionise-entire-website

4. Wipe out the current content of the gh-pages branch

$ uv run mike delete --all

5. Build the dev version of the documentation:

$ make gendoc

6. Deploy the dev version of the documentation and set it as the default version:

$ uv run mike deploy dev
$ uv run mike set-default dev

Now you need to build the website for version 1.0:

7. Checkout the tag corresponding to the 1.0 version:

$ git checkout v1.0.0

8. Amend pyproject.toml to add mike to the docs dependency group and amend mkdocs.yml to add the mike configuration (as is done on this PR, but now you need to back port that to your local checkout of the v1.0.0 tag).

9. Build the documentation for version 1.0. Remember that we were not using uv yet back in 1.0, so you must make sure you still have Poetry around:

$ make gendoc

10. Deploy the 1.0 documentation:

$ poetry run mike deploy 1.0

11. Switch back to the versionise-entire-website branch (strictly speaking not necessary, but this allows to be able to use uv back and avoid having to use Poetry more than strictly necessary):

$ git checkout versionise-entire-website

12. Launch a local web server to serve the entire website:

$ uv run mike serve

You can now browse the versionised website on https://localhost:8000/.

Once you are done with your tests, restore the original gh-pages:

$ git checkout gh-pages
$ git reset --hard savepoint
$ git checkout master

[gouttegd]

Alternatively, if you don’t want to have to bother with saving the state of the gh-pages branch, pass a -b <TEMPORARY_BRANCH_NAME> option to all calls to mike, as in:

$ uv run mike deploy -b test-mike dev
$ uv run mike set-default -b test-mike dev
... 
$ poetry run mike deploy -b test-mike 1.0
...
$ uv run mike serve -b test-mike

And then delete the test-mike branch when you’re done testing.

[gouttegd]

Alternatively, if you don’t want to have to bother with saving the state of the gh-pages branch, pass a -b <TEMPORARY_BRANCH_NAME> option to all calls to mike, as in:

[…]

I created and pushed a test-mike branch where all of that has already been done, so if you want an easy way to see the result:

1. Check-out the versionise-entire-website branch:

$ git branch -t versionise-entire-website origin/versionise-entire-website
$ git checkout versionise-entire-website

2. Have a local test-mike branch tracking the remote test-mike branch (no need to check it out).

$ git branch -t test-mike origin/test-mike

3. Run mike serve:

$ uv run mike serve -b test-mike

And browse the versionised website on http://localhost:8000/.

[matentzn]

This is fantastic. I tested it locally and it works great! Minor hypothetical comment,

[gouttegd]

Of note, before that PR is merged, we should merge the test-mike branch into gh-pages. This way, when we merge here and the deploy-documentation workflow is triggered, the gh-pages will be ready.

[cthoyt]

I didn't look into this carefully, but it's Friday so it's the perfect time to

[cthoyt]

this inadvertently broke the SSSOM schema PURLs like https://w3id.org/sssom/mapping_source, which still point to
https://mapping-commons.github.io/sssom/mapping_source/. This either needs to now point to https://mapping-commons.github.io/sssom/dev/mapping_source/ or https://mapping-commons.github.io/sssom/1.0/mapping_source/