docs: add banner for nightly version (#1931)

* docs: try and add notification for nightly version

* hmmm

* hmmmm

* I forgot to run the banner

* fix spacing

* some more comments

* fmt

.github/workflows/post_release.yml

@@ -70,14 +70,13 @@ jobs:
         run: ./scripts/ci/configure_git.sh
 
       # TODO: Test this with the script instead
+      # TODO: We no longer need the renaming logic after the next release!
       - name: Build and deploy docs with mike as the latest stable branch
         run: |
           cd docs
-          OLD_STABLE_VERSION=$(mike list stable | grep -Po '([0-9]+.[0-9]+.[0-9]+)' | head -n1)
+          OLD_STABLE_VERSION=$(mike list stable | grep -Po '(\d{1,3}\.\d{1,3}\.\d{1,3})' | head -n1)
           echo ${OLD_STABLE_VERSION}
           mike retitle --push stable ${OLD_STABLE_VERSION}
-          mike deploy --push --update-aliases ${RELEASE_VERSION} stable
-          mike retitle --push ${RELEASE_VERSION} "${RELEASE_VERSION} (stable)"
 
   chocolatey:
     needs: [initialize]

docs/content/overrides/main.html

@@ -1 +0,0 @@
-{% extends "base.html" %}

docs/hooks/nightly_banner.py

@@ -0,0 +1,17 @@
+import os
+import sys
+
+import mkdocs.plugins
+
+
+@mkdocs.plugins.event_priority(-100)
+def on_config(config):
+    print("Running nightly banner hook...", file=sys.stderr)
+
+    # From https://github.com/jimporter/mike/blob/3351d5feabff8ee107f4ad6d1f86055843c7dbf1/mike/mkdocs_utils.py#L13
+    version = os.environ.get("MIKE_DOCS_VERSION")
+    print(f"Version: {version}", file=sys.stderr)
+
+    if version == "nightly":
+        extra = config.get("extra", {})
+        extra["nightly"] = True

docs/hooks/nightly_redirect.py

@@ -1,7 +1,8 @@
 import os
+import sys
+import json
 import mkdocs.plugins
 import urllib.request
-import json
 
 
 # Based on https://github.com/squidfunk/mkdocs-material/discussions/3758#discussioncomment-4397373
@@ -9,7 +10,7 @@ import json
 
 @mkdocs.plugins.event_priority(-50)
 def on_config(config):
-    print("Running nightly release redirect hook...")
+    print("Running nightly release redirect hook...", file=sys.stderr)
     try:
         nightly_tag_name = None
         override = os.environ.get("MKDOCS_NIGHTLY_RELEASE_OVERRIDE")
@@ -35,8 +36,14 @@ def on_config(config):
             redirects = redirect_plugin.config.get("redirect_maps", {})
             redirects["nightly-release.md"] = nightly_release_url
 
-            print(f"Updated nightly release redirect to point to {nightly_release_url}")
+            print(
+                f"Updated nightly release redirect to point to {nightly_release_url}",
+                file=sys.stderr,
+            )
         else:
             print("nightly tag name was not set by any means.")
     except Exception as e:
-        print(f"error adjusting redirect, falling back to general releases page: {e}")
+        print(
+            f"error adjusting redirect, falling back to general releases page: {e}",
+            file=sys.stderr,
+        )

docs/mike.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+# Used to serve a versioned version of the docs locally. Note this
+# does NOT reflect local changes.
+
+set -e
+
+VENV_PATH="./.venv/"
+PYTHON_CMD=${1:-python}
+
+if [ ! -d $VENV_PATH ]; then
+    echo "venv not found, creating one using the command '${PYTHON_CMD}'...";
+    $PYTHON_CMD -m venv .venv;
+    source $VENV_PATH/bin/activate;
+    pip install --upgrade pip;
+    pip install -r requirements.txt;
+    $VENV_PATH/bin/mike serve;
+else
+    echo "venv already found.";
+    source $VENV_PATH/bin/activate;
+    pip install --upgrade pip;
+    pip install -r requirements.txt;
+    $VENV_PATH/bin/mike serve;
+fi;
+

docs/mkdocs.yml

@@ -54,7 +54,7 @@ theme:
       toggle:
         icon: material/weather-night
         name: Switch to system preference
-  custom_dir: "content/overrides"
+  custom_dir: "overrides"
 extra_css:
   - stylesheets/extra.css
 
@@ -147,6 +147,8 @@ extra:
     provider: mike
     default: stable
     alias: true
+  # Used for the nightly banner
+  nightly: false
 
 # Navigation
 nav:
@@ -191,4 +193,8 @@ nav:
   - "Troubleshooting": troubleshooting.md
 
 hooks:
-  - ./hooks/nightly_redirect.py
+  - ./hooks/nightly_redirect.py
+  - ./hooks/nightly_banner.py
+
+exclude_docs: |
+  nightly-release.md

docs/overrides/main.html

@@ -0,0 +1,10 @@
+{% extends "base.html" %}
+{% block announce %}
+    <!-- It's like helm and you need to add dashes, see https://github.com/squidfunk/mkdocs-material/discussions/5803#discussioncomment-7690065 -->
+    {%- if config.extra.nightly -%}
+    <!-- Need to reapply margin from base CSS, which is overridden in extra CSS (to fix empty banner) -->
+    <div style="margin: 0.6rem auto">
+        This is <strong>nightly</strong> documentation, and it may differ from stable. Please see <strong><a href="{{ '../' ~ base_url }}">here for stable documentation</a></strong>.
+    </div>
+    {%- endif -%}
+{% endblock %}