Use mike for docs versioning

- Add version warning
- Auto deploy docs to `gh-pages` on github release

The commit is kept here as a reference.

We will switch to readthedocs to deploy multiple versions of the docs,
since mike use `gh-pages` branch to host the docs, increasing the size
of the repo in the long term. See wannier-developers#485 for more details.

.github/workflows/docs.yml

@@ -1,36 +1,43 @@
-name: Build docs
+name: Deploy docs
+
 on:
-  pull_request:
-  push:
-    branches:
-      - develop
+  release:
+    types: [published]
 
 jobs:
-  docs:
-      name: Build docs
-      runs-on: ubuntu-latest
-      steps:
-        - uses: actions/checkout@v4
-        - uses: actions/setup-python@v5
-          with:
-            python-version: "3.11"
-        - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-        - uses: actions/cache@v4
-          with:
-            key: mkdocs-w90-${{ env.cache_id }}
-            path: .cache
-            restore-keys: |
-              mkdocs-w90-
-        - run: pip install -r docs/requirements.txt
-        - run: mkdocs build -s
-          working-directory: ./docs
-          env:
-            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-            ENABLE_MKDOCS_GIT_COMMITTERS: False
+  deploy_docs:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: git fetch origin gh-pages --depth=1
+      - run: |
+          git config user.name github-actions
+          git config user.email [email protected]
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+      - run: pip install -r docs/requirements.txt
+
+      # This deploys mkdocs-built html, now we use mike to deploy
+      # html to have doc versioning.
+      #
+      # - run: mkdocs build -s
+      #   working-directory: ./docs
+      #   env:
+      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      #     ENABLE_MKDOCS_GIT_COMMITTERS: True
+      # - name: Deploy to GitHub Pages
+      #   uses: peaceiris/actions-gh-pages@v3
+      #   if: github.ref == 'refs/heads/develop'
+      #   with:
+      #     github_token: ${{ secrets.GITHUB_TOKEN }}
+      #     publish_dir: ./docs/site
 
-        - name: Deploy to GitHub Pages
-          uses: peaceiris/actions-gh-pages@v3
-          if: github.ref == 'refs/heads/develop'
-          with:
-            github_token: ${{ secrets.GITHUB_TOKEN }}
-            publish_dir: ./docs/site
+      - name: mike deploy
+        run: mike deploy --push --update-aliases ${{ github.ref_name }} latest
+        working-directory: ./docs
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ENABLE_MKDOCS_GIT_COMMITTERS: True

.github/workflows/main.yml

@@ -4,8 +4,8 @@ on:
   pull_request:
   push:
     branches:
-    - develop
-    
+      - develop
+
 jobs:
   pre-commit:
     runs-on: ubuntu-20.04
@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-20.04
     strategy:
       matrix:
-        w90-binary-parallel: [ 'false', 'true' ]
+        w90-binary-parallel: ["false", "true"]
     name: Build and test `parallel=${{ matrix.w90-binary-parallel }}`
     steps:
       - name: checkout
@@ -66,3 +66,19 @@ jobs:
           path: |
             test-suite/tests/test*/test.err*
             test-suite/tests/test*/test.out*
+
+  docs:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+      - run: pip install -r docs/requirements.txt
+      - run: mkdocs build -s
+        working-directory: ./docs
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ENABLE_MKDOCS_GIT_COMMITTERS: False

docs/README.md

@@ -24,6 +24,51 @@ pip install -r requirements.txt
 * `mkdocs build` - Build the documentation site.
 * `mkdocs -h` - Print help message and exit.
 
+## Versioning
+
+[`mike`](https://github.com/jimporter/mike) is used to manage the versioning of
+the documentation.
+
+In general, one can manually deploy the docs when a new version is released, by
+
+```bash
+mike deploy --push --update-aliases v[MAJOR].[MINOR] latest
+```
+
+Then the docs will be committed and pushed to the `gh-pages` branch.
+
+For development, one can use
+
+```bash
+mike serve
+```
+
+To list the available versions, use
+
+```bash
+mike list
+```
+
+### `miki` initialization
+
+For future reference, these are the commands used for initializing the
+`gh-pages` branch
+
+```bash
+mike delete --all  # clean gh-pages branch
+mike deploy --push --update-aliases v3.1.0 latest  # build docs
+mike set-default latest  # set default redirect to latest
+```
+
+No need to run these commands again!
+For future releases, just use `mike deploy`.
+
+### References
+
+* <https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning>
+* <https://github.com/squidfunk/mkdocs-material-example-versioning>
+* <https://github.com/jimporter/mike>
+
 ## Notes on conversion
 
 The original wannier90 latex documentation was converted to markdown using

docs/mkdocs.yml

@@ -125,6 +125,7 @@ theme:
     code: Roboto Mono
   logo: assets/wannier-logo-squared.svg
   favicon: assets/wannier-logo-squared.png
+  custom_dir: overrides
 
 extra:
   status:
@@ -136,6 +137,8 @@ extra:
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/wannier-developers/wannier90
+  version:
+    provider: mike
 
 markdown_extensions:
   - abbr

docs/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 %}

docs/requirements.txt

@@ -5,3 +5,4 @@ mkdocs-git-revision-date-localized-plugin==1.2.4
 mkdocs-git-committers-plugin-2==2.2.3
 mkdocs-bibtex==2.12.0
 mkdocs-glightbox==0.3.7
+mike==2.0.0