Merge pull request #216 from minijackson/docs-multiversion

Multiversionned docs

.github/workflows/book-gh-pages.yml

@@ -4,7 +4,9 @@ on:
   # Allows running this workflow manually
   workflow_dispatch:
   push:
-    branches: [master]
+    branches:
+      - master
+      - nixos-24.05
 
 permissions:
   contents: read
@@ -17,22 +19,38 @@ concurrency:
 jobs:
   deploy:
     if: "github.repository_owner == 'epics-extensions'"
+
     permissions:
       pages: write
       id-token: write
+
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
+
     runs-on: ubuntu-latest
+
     steps:
+
+      # Checkout all documentation versions
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
+          ref: main
+          path: dev
           persist-credentials: false
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          ref: nixos-24.05
+          path: nixos-24.05
+          persist-credentials: false
+
       - uses: cachix/install-nix-action@3715ab1a11cac9e991980d7b4a28d80c7ebdd8f9 # v27
-      - name: "Build documentation book"
+      - uses: DeterminateSystems/magic-nix-cache-action@87b14cf437d03d37989d87f0fa5ce4f5dc1a330b # v8
+
+      - name: "Build documentation books"
         run: |
-          nix build '.#docs' --print-build-logs
-          cp -Lr --no-preserve=mode,ownership ./result/share/doc/epnix/html ./book
+          nix run --print-build-logs './dev#ci-scripts/build-docs-multiversion'
+
       - name: Setup Pages
         uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
       - name: Upload artifact

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 = "dev"
 
 source_repository = "https://github.com/epics-extensions/EPNix"
 
@@ -77,14 +80,16 @@
 
 nix_options_json_files = ["./nixos-options.json"]
 
+
 def nix_linkcode_resolve(path: str) -> str:
     return f"{source_repository}/blob/master/{path}"
 
+
 # -- Options for HTML output -------------------------------------------------
 # 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 = {
@@ -116,6 +121,34 @@ def nix_linkcode_resolve(path: str) -> str:
 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
 

pkgs/ci-scripts/build-docs-multiversion.nix

@@ -0,0 +1,47 @@
+{
+  writeShellApplication,
+  writeText,
+  writers,
+  epnixLib,
+}: let
+  stable = "nixos-24.05";
+  versions = [
+    "dev"
+    "nixos-24.05"
+  ];
+  baseurl = "https://epics-extensions.github.io/EPNix";
+  # Make a redirection using the <meta> tag,
+  # with a delay of 1 second, because Google considers them not permanent
+  #
+  # We need non-permanent redirections, because the redirection will change
+  # when a new stable version is released
+  redirect = writeText "stable-redirect.html" ''
+    <meta http-equiv=refresh content="1;url=${stable}/">
+  '';
+
+  versionInfo = ver: {
+    name = ver;
+    url = "${baseurl}/${ver}/";
+  };
+  versions_json = writers.writeJSON "versions.json" (map versionInfo versions);
+in
+  writeShellApplication {
+    name = "build-docs-multiversion";
+
+    text = ''
+      for version in ${toString versions}; do
+        mkdir -p "./book/$version"
+        cp ${versions_json} "./$version/docs/versions.json"
+        git -C "$version" add docs/versions.json
+        nix build "./$version#docs" --print-build-logs
+        cp -LrT --no-preserve=mode,ownership ./result/share/doc/epnix/html "./book/$version"
+      done
+      cp ${redirect} ./book/index.html
+    '';
+
+    meta = {
+      description = "Build ";
+      maintainers = with epnixLib.maintainers; [minijackson];
+      hidden = true;
+    };
+  }

pkgs/default.nix

@@ -106,5 +106,9 @@ in
 
       # Documentation support packages
       psu-simulator = callPackage ./doc-support/psu-simulator {};
+
+      ci-scripts = recurseExtensible (_self: {
+        build-docs-multiversion = callPackage ./ci-scripts/build-docs-multiversion.nix {};
+      });
     });
   }