From 347f7dc96873bd08d6d5c9770e0a1c93940c5800 Mon Sep 17 00:00:00 2001
From: Heinz-Alexander Fuetterer <35225576+afuetterer@users.noreply.github.com>
Date: Fri, 17 May 2024 11:16:41 +0200
Subject: [PATCH] docs: set up versioned docs with mike (#374)

Fixes #352
---
 .github/dependabot.yml       | 1 +
 .github/workflows/docs.yml   | 6 ++++++
 docs/mkdocs.yml              | 7 +++++++
 docs/src/overrides/main.html | 8 ++++++++
 pyproject.toml               | 3 ++-
 5 files changed, 24 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/overrides/main.html

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 7267943..fdc5f87 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -30,6 +30,7 @@ updates:
   groups:
     docs:
       patterns:
+      - mike
       - mkdocs*
     test:
       patterns:
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index ed1172f..65c55bb 100644
--- a/.github/workflows/docs.yml
+++ b/.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
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 6ddc94a..c56df05 100644
--- a/docs/mkdocs.yml
+++ b/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
diff --git a/docs/src/overrides/main.html b/docs/src/overrides/main.html
new file mode 100644
index 0000000..0af326a
--- /dev/null
+++ b/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 %}
diff --git a/pyproject.toml b/pyproject.toml
index 87ff1af..22bdb2e 100644
--- a/pyproject.toml
+++ b/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/