Merge pull request #54 from rl-institut/feature-36-mike-workflow

Improve the mike workflow

CHANGELOG.md

@@ -10,13 +10,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- [(#)]()
+- Add a favicon for the documentation [(54#)](https://github.com/rl-institut/super-repo/pull/54)
+- Add a warning for older versions that links to latest [(#54)](https://github.com/rl-institut/super-repo/pull/54)
 
 ### Changed
-- [(#)]()
+- Update CSS to improve toc [(#54)](https://github.com/rl-institut/super-repo/pull/54)
+- Update documentation for mike [(#54)](https://github.com/rl-institut/super-repo/pull/54)
 
 ### Removed
-- [(#)]()
+- Disable GitHub Action for MkDocs Workflow [(#54)](https://github.com/rl-institut/super-repo/pull/54)
 
 
 ## [0.2.0] Minor Release - Oh Hi Mike - 2023-08-11

RELEASE_PROCEDURE.md

@@ -123,7 +123,6 @@ If you messed up, remove tags and start again
 * Activate environment and enter repository
 * Test version with `mike serve`
 * Publish new minor version `mike deploy --push --update-aliases 0.1 latest`
-* Set new version as latest `mike set-default --push latest`
 
 ▶️ Update the documentation!
 
@@ -136,13 +135,10 @@ If you messed up, remove tags and start again
 ## [Unreleased]
 
 ### Added
-- [(#)]()
 
 ### Changed
-- [(#)]()
 
 ### Removed
-- [(#)]()
 ```
 
 ▶️ Continue the developments 🛠

docs/css/extra.css

@@ -4,4 +4,7 @@
     --md-typeset-a-color: #5ba6ec;
     /* --md-text-font-color:         #ffffff;  */
     /* --md-primary-fg-color--light: #ECB7B7; */
-  }
+  }
+
+:not([data-md-state="blur"]) + nav {
+  display: none;

docs/development/documentation/index.md

@@ -30,18 +30,42 @@ Generate the documentation locally. <br>
 Publish documentation on **GitHub Pages**. <br>
 💻 `mkdocs gh-deploy` manually deploys the documentation files
 
-#### GitHub Action
+#### GitHub Action (deprecated)
 🐙 Deploy the documentation with **GitHub Actions**. <br>
 The file `.github\workflows\gh-pages.yml` creates an automated GitHub workflow. <br>
 It is configured to be pushed to the branch `gh-page` and then deployed online. <br>
 A commit on the `production` branch triggers the workflow. 
 
+!!! warning "Using mike with GitHub Actions"
+    This feature is not compatible with the versioning of the documentation with `mike`.<br>
+    The action overrides all manually deployed versions!
+
+🐙 To disable an existing `GitHub Action`, follow these instructions:<br>
+https://docs.github.com/de/enterprise-cloud@latest/actions/using-workflows/disabling-and-enabling-a-workflow
+
 ### Mike
 The package [mike](https://github.com/jimporter/mike) is used to deploy [multiple versions](https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/?h=versioning) of the documentation.<br>
 💻 `pip install mike` install mike <br>
-💻 `mike deploy --push --update-aliases 0.1.0 latest` deploys the latest version <br>
+💻 `mike deploy --push --update-aliases 0.1 latest` deploys the latest version <br>
 💻 `mike set-default --push latest` Set the default version to latest
 
+!!! note "Mike Versions"
+    It is recommended to use only the Minor Versions (e.g. 0.1) and exclude the patch number.
+
+Other useful commands are:
+error: gh-pages is unrelated to origin/gh-pages`mike serve` test mike on `http://localhost:8000` <br>
+💻 `mike list` list all versions <br>
+💻 `mike retitle 1.0.0 1.0.1 --push` list all versions <br>
+💻 `mike delete --all --push` deletes all versions
+
+When building mike locally, the branch `gh-pages` is modified locally.
+💻 `error: gh-pages is unrelated to origin/gh-pages` <br>
+💠 `git branch -D gh-pages` delete the local documentation branch
+
+When adding older versions, load the `Git Tags` used for the releases:
+💠 `git checkout v0.1` 
+💻 `mike deploy --push --update-aliases 0.1 latest` deploys the old version <br>
+
 ## mkdocstrings
 [mkdocstrings](https://mkdocstrings.github.io/) generates automatic 
 documentation (autodocs) from [Google style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). <br>

docs/overrides/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  This is not the latest version.
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Go to latest.</strong>
+  </a>
+{% endblock %}

mkdocs.yml

@@ -12,6 +12,7 @@ docs_dir: docs
 theme:
   name: material
   logo: img/logo_rli_small.png
+  favicon: img/logo_rli_small.png
   palette:
     # Palette toggle for dark mode
     - scheme: slate