docs: Add site version via mike

mike is a tool to keep several versions of a MkDocs site.

Please see the project documentation for more info:
https://github.com/jimporter/mike

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

CONTRIBUTING.md

@@ -60,6 +60,39 @@ Or you can just serve the documentation without building it using:
 mkdocs serve
 ```
 
+Your site will be updated **live** when you change your files (provided that
+you used `pip install -e .`, beware of a common pitfall of using `pip install`
+without `-e`, in that case the API reference won't change unless you do a new
+`pip install`).
+
+To build multi-version documentation, we use
+[mike](https://github.com/jimporter/mike). If you want to see how the
+multi-version sites looks like locally, you can use:
+
+```sh
+mike deploy my-version
+mike set-default my-version
+mike serve
+```
+
+`mike` works in mysterious ways. Some basic information:
+
+* `mike deploy` will do a `mike build` and write the results to your **local**
+  `gh-pages` branch. `my-version` is an arbitrary name for the local version
+  you want to preview.
+* `mike set-default` is needed so when you serve the documentation, it goes to
+  your newly produced documentation by default.
+* `mike serve` will serve the contents of your **local** `gh-pages` branch. Be
+  aware that, unlike `mkdocs serve`, changes to the sources won't be shown
+  live, as the `mike deploy` step is needed to refresh them.
+
+Be careful not to use `--push` with `mike deploy`, otherwise it will push your
+local `gh-pages` branch to the `origin` remote.
+
+That said, if you want to test the actual website in **your fork**, you can
+always use `mike deploy --push --remote your-fork-remote`, and then access the
+GitHub pages produced for your fork.
+
 ## Releasing
 
 These are the steps to create a new release:

docs/overrides/main.html

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

mkdocs.yml

@@ -19,6 +19,7 @@ theme:
   icon:
     edit: material/file-edit-outline
     repo: fontawesome/brands/github
+  custom_dir: docs/overrides
   features:
     - navigation.instant
     - navigation.tabs
@@ -47,6 +48,9 @@ extra:
     link: https://github.com/frequenz-floss
   - icon: fontawesome/brands/linkedin
     link: https://www.linkedin.com/company/frequenz-com
+  version:
+    provider: mike
+    default: latest
 
 extra_css:
   - css/style.css
@@ -76,6 +80,8 @@ plugins:
         - docs/mkdocstrings_autoapi.py
   - literate-nav:
       nav_file: SUMMARY.md
+  - mike:
+      canonical_version: latest
   - mkdocstrings:
       custom_templates: templates
       default_handler: python

pyproject.toml

@@ -3,7 +3,6 @@ requires = [
     "setuptools >= 65.3.0, < 66",
     "setuptools_scm[toml] >= 7.0.5, < 8",
     "wheel"
-
 ]
 build-backend = "setuptools.build_meta"
 
@@ -49,6 +48,7 @@ email = "[email protected]"
 
 [project.optional-dependencies]
 docs = [
+    "mike >= 1.1.2, < 2",
     "mkdocs-gen-files >= 0.4.0, < 0.5.0",
     "mkdocs-literate-nav >= 0.4.0, < 0.5.0",
     "mkdocs-material >= 8.5.7, < 9",