Add: mike for documentation versioning

Author: nicola-corbellini

.github/workflows/gh-pages.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - dev
 
 jobs:
   build-deploy:
@@ -12,6 +13,9 @@ jobs:
       # 1. Checkout repo (code + docs)
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GH_PAGES_TOKEN || github.token }}
 
       # 2. Set up Python
       - name: Set up Python
@@ -23,19 +27,19 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install .[dev]   # installs mkdocs and all extras
+          pip install .[dev] mike
 
-      # 4. Build doc
-      - name: Build MkDocs site
+      # 4. Deploy MkDocs site with mike
+      - name: Deploy with mike 🚀
         env:
           PYTHONPATH: ${{ github.workspace }}/PyEyesWeb
-        run: mkdocs build --verbose
-
-      # 5. Push to gh-pages
-      - name: Deploy to GitHub Pages 🚀
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GH_PAGES_TOKEN }}
-          publish_dir: ./site
-          publish_branch: gh-pages
-          force_orphan: true
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          
+          if [ "${{ github.ref_name }}" = "main" ]; then
+            mike deploy --push --update-aliases main latest
+            mike set-default --push latest
+          else
+            mike deploy --push ${{ github.ref_name }}
+          fi

.gitignore

@@ -44,4 +44,7 @@ demos/Backup
 demos/Lib
 
 # Ignore specific files or directories
-__*
+__*
+
+# Ignore the site directory
+site/

docs/javascripts/version-select.js

@@ -0,0 +1,52 @@
+document.addEventListener("DOMContentLoaded", function() {
+    // Determine base URL based on environment (localhost vs GitHub Pages)
+    var isLocalhost = window.location.hostname === "localhost" || window.location.hostname === "127.0.0.1";
+    var baseUrl = isLocalhost ? "" : "/PyEyesWeb";
+
+    // Attempt to fetch the versions.json generated by mike
+    fetch(baseUrl + "/versions.json").then(response => {
+        if (!response.ok) return null;
+        return response.json();
+    }).then(versions => {
+        if (!versions || versions.length === 0) return;
+        
+        // Find the current version from the URL path. 
+        var pathSegments = window.location.pathname.split('/').filter(p => p !== "");
+        // If localhost: /dev/ -> pathSegments[0] is "dev"
+        // If GitHub: /PyEyesWeb/dev/ -> pathSegments[1] is "dev"
+        var currentVersion = isLocalhost ? pathSegments[0] : pathSegments[1]; 
+        
+        if (!currentVersion) {
+            currentVersion = versions[0].version; // fallback if at root
+        }
+        
+        var select = document.createElement("select");
+        select.style.margin = "10px auto";
+        select.style.display = "block";
+        select.style.width = "90%";
+        select.style.padding = "5px";
+        select.style.color = "#000";
+        select.style.borderRadius = "3px";
+        select.style.border = "1px solid #ccc";
+        
+        versions.forEach(function(version) {
+            var option = document.createElement("option");
+            option.value = version.version;
+            option.text = "Version: " + version.title;
+            if (version.version === currentVersion || version.aliases.includes(currentVersion)) {
+                option.selected = true;
+            }
+            select.appendChild(option);
+        });
+
+        select.addEventListener("change", function() {
+            window.location.href = baseUrl + "/" + this.value + "/";
+        });
+
+        // Add the dropdown to the readthedocs sidebar search box or navigation container
+        var searchBox = document.querySelector(".wy-side-nav-search");
+        if (searchBox) {
+            searchBox.appendChild(select);
+        }
+    }).catch(e => console.error("Error loading versions.json:", e));
+});

mkdocs.yml

@@ -33,9 +33,6 @@ markdown_extensions:
       pygments_lang_class: true
   - pymdownx.inlinehilite
   - pymdownx.keys
-  - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.arithmatex:
       generic: true
 
@@ -44,61 +41,14 @@ theme:
   custom_dir: docs/overrides
   logo: assets/eyesweb-logo.png
   favicon: assets/favicon-32x32.png
-  icon:
-    repo: fontawesome/brands/github
-#  font:
-#    text: Inter
-  features:
-    - navigation.tabs
-    - navigation.tabs.sticky
-    - navigation.instant
-    - navigation.path
-    - navigation.indexes
-    - navigation.top
-    - navigation.footer
-#    - navigation.expand
-    - content.code.copy
-    - content.tabs.link
-    - content.tooltips
-    - content.code.annotate
-    - content.tables.striped
-    - search.suggest
-    - search.highlight
-    - search.share
-    - toc.follow
-    - announce.dismiss
-  palette:
-    - media: "(prefers-color-scheme: light)"
-      scheme: default
-      primary: red
-      accent: indigo
-      toggle:
-        icon: material/weather-night
-        name: Switch to dark mode
-    - media: "(prefers-color-scheme: dark)"
-      scheme: slate
-      primary: black
-      accent: red
-      toggle:
-        icon: material/weather-sunny
-        name: Switch to light mode
-
 extra_javascript:
   - javascripts/mathjax.js
   - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
+  - javascripts/version-select.js
 
 extra_css:
   - overrides/extra.css
 
-extra:
-  social:
-    - icon: fontawesome/brands/github
-      link: https://github.com/InfoMusCP
-      name: GitHub Organization
-    - icon: material/web
-      link: http://www.casapaganini.org/index_eng.php
-      name: Casa Paganini - InfoMus Website
-
 copyright: Copyright © 2025 Casa Paganini - InfoMus, Genoa, Italy. All rights reserved.
 
 nav: