docs: set up versioned docs with mike (#374)

Fixes #352

.github/dependabot.yml

@@ -30,6 +30,7 @@ updates:
   groups:
     docs:
       patterns:
+      - mike
       - mkdocs*
     test:
       patterns:

.github/workflows/docs.yml

@@ -23,6 +23,8 @@ jobs:
       contents: write
     steps:
     - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      with:
+        fetch-depth: 0 # fetch all commits and branches
     - name: Set up Python 3.12
       uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0
       with:
@@ -34,5 +36,9 @@ jobs:
     - name: Install pre-requisites (e.g. hatch)
       run: python -m pip install --require-hashes --requirement=.github/requirements/ci.txt
     - run: hatch run docs:build
+      if: github.event_name == 'pull_request'
     - run: hatch run docs:deploy
       if: contains(fromJSON('["release", "workflow_dispatch"]'), github.event_name)
+      env:
+        GIT_COMMITTER_NAME: github-actions[bot]
+        GIT_COMMITTER_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com

docs/mkdocs.yml

@@ -4,6 +4,7 @@
 
 site_name: oaipmh-scythe
 site_description: A Scythe for harvesting OAI-PMH repositories.
+site_url: https://afuetterer.github.io/oaipmh-scythe/
 repo_name: afuetterer/oaipmh-scythe
 repo_url: https://github.com/afuetterer/oaipmh-scythe
 docs_dir: src
@@ -31,6 +32,7 @@ nav:
 
 theme:
   name: material
+  custom_dir: src/overrides
   features:
   - content.action.edit
   - content.action.view
@@ -73,3 +75,8 @@ markdown_extensions:
 - pymdownx.inlinehilite
 - pymdownx.snippets
 - pymdownx.superfences
+
+extra:
+  version:
+    provider: mike
+    alias: true

docs/src/overrides/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}

pyproject.toml

@@ -41,6 +41,7 @@ dev = [
   "pre-commit~=3.6",
 ]
 docs = [
+  "mike~=2.0",
   "mkdocs~=1.5",
   "mkdocs-include-markdown-plugin~=6.0",
   "mkdocs-material~=9.5",
@@ -101,7 +102,7 @@ template = "docs"
 [tool.hatch.envs.docs.scripts]
 build = "mkdocs build --config-file=docs/mkdocs.yml"
 serve = "mkdocs serve --verbose --config-file=docs/mkdocs.yml"
-deploy = "mkdocs gh-deploy --force --config-file=docs/mkdocs.yml"
+deploy = "mike deploy --push --update-aliases $(hatch version) latest --config-file=docs/mkdocs.yml"
 
 # ruff
 # Ref: https://docs.astral.sh/ruff/configuration/