docs: support multiple versions

docs/_static/multi-version.css

@@ -0,0 +1,44 @@
+.multi-version {
+	font-size: var(--sidebar-item-font-size);
+	border-top: 1px solid var(--color-background-border);
+	margin-bottom: 1em;
+}
+
+.multi-version summary {
+	color: var(--color-sidebar-caption-text);
+	font-size: var(--sidebar-caption-font-size);
+	font-weight: 700;
+	text-transform: uppercase;
+
+	margin: 0;
+	padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);
+}
+
+.multi-version ul {
+	display: grid;
+	grid-template-columns: 1fr 1fr;
+
+	list-style: none;
+	padding: 0;
+	margin: 0;
+}
+
+.multi-version ul a {
+	box-sizing: border-box;
+	display: inline-block;
+	height: 100%;
+	line-height: var(--sidebar-item-line-height);
+	overflow-wrap: anywhere;
+	padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);
+	text-decoration: none;
+	width: 100%;
+}
+
+.multi-version summary:hover,
+.multi-version ul a:hover {
+	background: var(--color-background-hover);
+}
+
+.multi-version ul a.current {
+	font-weight: 700;
+}

docs/_templates/multi-version.html

@@ -0,0 +1,18 @@
+{% if versions %}
+<div class="multi-version">
+  <details>
+    <summary>{{ _('Versions') }}:</summary>
+    <ul>
+      {%- for item in versions %}
+      <li>
+        {% if item.current %}
+        <a href="{{ item.url }}" class="current">{{ item.name }}</a>
+        {% else %}
+        <a href="{{ item.url }}">{{ item.name }}</a>
+        {% endif %}
+      </li>
+      {%- endfor %}
+    </ul>
+  </details>
+</div>
+{% endif %}

docs/conf.py

@@ -3,8 +3,10 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import json
 import os
 import sys
+from pathlib import Path
 
 # Enables importing our custom "pygments_styles" module
 sys.path.append(os.path.abspath("./_ext"))
@@ -15,6 +17,7 @@
 project = "EPNix"
 copyright = "The EPNix Contributors"
 author = "The EPNix Contributors"
+release = "nixos-24.05"
 
 language = "en"
 
@@ -73,7 +76,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_static_path = ["_static"]
-html_baseurl = "https://epics-extensions.github.io/EPNix/"
+html_baseurl = f"https://epics-extensions.github.io/EPNix/{release}/"
 
 html_theme = "furo"
 html_theme_options = {
@@ -105,6 +108,34 @@
 html_logo = "logo.svg"
 html_favicon = "favicon.svg"
 
+# Multi version
+
+html_sidebars = {
+    "**": [
+        "sidebar/brand.html",
+        "sidebar/search.html",
+        "sidebar/scroll-start.html",
+        "sidebar/navigation.html",
+        "sidebar/scroll-end.html",
+        "multi-version.html",
+    ]
+}
+
+html_css_files = ["multi-version.css"]
+
+html_context = {}
+
+versions = Path("./versions.json")
+if versions.exists():
+    with versions.open() as f:
+        html_context["versions"] = json.load(f)
+
+    # Mark current version as current
+    current_version = next(
+        el for el in html_context["versions"] if el["name"] == release
+    )
+    current_version["current"] = True
+
 # -- Options for Man output --------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-manual-page-output